Pular para o conteúdo
SvgJsx
Idioma: Português

Como usar ícones SVG no React

Existem cinco formas comuns de colocar ícones SVG em um app React. Este guia compara cada uma em desempenho, estilo e acessibilidade e mostra quando cada uma é a escolha certa.

Predefinições:
Solte arquivos .svg aqui ouOs arquivos são lidos localmente com FileReader e nunca são enviados.
Opções
Exportação:
import type { SVGProps } from "react";

const HeartIcon = ({ size = 24, ...props }: SVGProps<SVGSVGElement> & { size?: number | string }) => (
  <svg viewBox="0 0 24 24" className="icon icon-heart" width={size} height={size} {...props}>
    <g id="Layer_1" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
      <path d="M19.0001 14.0002c1.4900-1.4600 3.0000-3.2100 3.0000-5.5000A5.5000 5.5000 0 0 0 16.5000 3c-1.7600 0-3.0000.5000-4.5000 2-1.5000-1.5000-2.7400-2-4.5000-2A5.5000 5.5000 0 0 0 2 8.5000c0 2.3000 1.5000 4.0500 3 5.5000l7 7Z" style={{ fillOpacity: "0.15", fill: "currentColor" }} />
    </g>
  </svg>
);

export default HeartIcon;

Pré-visualização

Pré-visualização do SVG convertido
SVG original
706 B
SVG otimizado
548 B(-22%)
Componente
692 B

1. Componentes SVG inline

Converter cada ícone em um componente (a abordagem que este site automatiza) dá controle total: os ícones herdam a cor via currentColor, aceitam props como size e className e podem ser animados com CSS ou uma biblioteca de animação. Os bundlers eliminam componentes não usados (tree shaking), então você só envia os ícones que importa.

A contrapartida é que a marcação passa a fazer parte do bundle JavaScript. Para algumas dezenas de ícones pequenos isso é irrelevante; para centenas de ilustrações complexas, não.

2. Tags img e fundos CSS

<img src="/logo.svg" alt="Empresa"> é a opção mais simples, e o navegador consegue armazenar o arquivo em cache. Porém o SVG fica isolado do seu CSS, então não dá para mudar a cor no hover ou no modo escuro. Use para logos e ilustrações que nunca mudam.

3. SVGR e loaders em tempo de build

O SVGR (via @svgr/webpack ou vite-plugin-svgr) converte imports de .svg em componentes durante o build. É prático para pastas grandes de ícones, mas adiciona configuração de build e pode se comportar de forma diferente entre bundlers e no Turbopack. Converter uma vez com esta ferramenta gera o mesmo tipo de componente como código-fonte versionado.

4. Sprites SVG e 5. bibliotecas de ícones

Um sprite reúne muitos elementos <symbol> em um arquivo e os referencia com <use href="#icone">. Isso mantém o HTML enxuto, mas complica a renderização no servidor. Bibliotecas como Lucide, Heroicons e Phosphor trazem componentes prontos e são ideais quando o estilo delas combina com o seu design.

Seja qual for o método, siga estas regras de acessibilidade:

  • Ícones decorativos ao lado de texto recebem aria-hidden="true".
  • Ícones isolados, como um botão só com ícone, precisam de um nome acessível via aria-label no botão ou um <title> dentro do SVG.
  • Mantenha um viewBox e dimensione os ícones em em ou rem para que acompanhem o tamanho de fonte do usuário.
  • Garanta uma razão de contraste de pelo menos 3:1 para ícones com significado (WCAG 1.4.11).

Perguntas frequentes

Qual é a melhor forma de usar ícones SVG no React?

Para ícones de interface, componentes inline com currentColor e uma prop size são os mais flexíveis. Use <img> para artes estáticas e uma biblioteca de ícones quando o estilo dela combinar com o seu design.

Ícones SVG inline prejudicam o desempenho?

Raramente. Um ícone típico de 24×24 tem de 300 a 600 bytes depois de otimizado. Os problemas só aparecem com centenas de ícones complexos renderizados ao mesmo tempo, e aí um sprite ou <img> é melhor.

Devo usar SVGR ou converter os ícones manualmente?

O SVGR combina com conjuntos de ícones grandes, que mudam com frequência, e um pipeline de build estável. Componentes pré-convertidos não exigem configuração e funcionam igual em qualquer bundler.

Como deixar ícones SVG acessíveis?

Esconda ícones decorativos com aria-hidden="true" e dê aos ícones com significado um nome acessível com aria-label ou <title>. Nunca dependa só de um ícone para transmitir informações importantes.

Como dimensionar ícones SVG com Tailwind?

Remova width e height fixos, mantenha o viewBox e aplique classes como size-5 ou h-4 w-4. Outra opção é ativar a prop size e passar um número.