Como usar ícones SVG em HTML, CSS, React e Vue

Ícones SVG são pequenos arquivos vetoriais: ficam nítidos em qualquer tamanho, pesam poucas centenas de bytes e podem ter a cor alterada com CSS. Existem quatro formas comuns de colocá-los em uma página. A melhor depende de você precisar estilizar o ícone, de quantos ícones a página tem e do framework que você usa.

1. Usar o SVG com uma tag <img>

O método mais simples: trate o ícone como qualquer outra imagem. Todo ícone do Iconyz tem uma URL SVG pública, exibida no painel do ícone.

<img src="https://iconyz.com/api/public/svg/lucide/house.svg"
     width="24" height="24" alt="Início">

O navegador guarda o arquivo em cache, e o ícone nunca bloqueia a renderização do HTML. A desvantagem é que o CSS não alcança o interior de uma imagem, então estilos de color e :hover não têm efeito. Em ícones monocromáticos, você pode definir a cor na URL: adicione ?color=%23e11d48 (#e11d48 codificado para URL). Veja os detalhes no guia da API de SVG.

Em aplicações em produção, considere baixar o SVG e servi-lo do seu próprio site, para que suas páginas não dependam de uma URL de terceiros.

2. Colar o SVG inline

Abra um ícone, escolha SVG e copie o código direto para o seu HTML:

<button class="btn">
  <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"
       aria-hidden="true">
    <path fill="none" stroke="currentColor" stroke-width="2" d="…"/>
  </svg>
  Início
</button>

O SVG inline faz parte da página, então o CSS controla tudo: cor, tamanho, estados de hover, transições e até traçados específicos. Coleções monocromáticas usam currentColor, então o ícone assume automaticamente a cor do texto do elemento pai. É a opção mais flexível e não exige nenhuma requisição HTTP extra.

O custo é o tamanho do HTML. Cada ícone inline adiciona seus traçados a todas as páginas que o usam, o que pesa quando o mesmo ícone se repete centenas de vezes, por exemplo em uma tabela longa.

3. Usar o ícone pelo CSS

Uma máscara CSS transforma qualquer SVG monocromático em uma forma preenchida com background-color, então o ícone segue a cor do texto sem que a marcação fique no HTML:

.icon-home {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  -webkit-mask: url("https://iconyz.com/api/public/svg/lucide/house.svg") no-repeat center / contain;
          mask: url("https://iconyz.com/api/public/svg/lucide/house.svg") no-repeat center / contain;
}

<span class="icon-home" aria-hidden="true"></span>

A aba CSS do painel de cada ícone gera essa regra com o SVG embutido como data URI, então ela funciona sem nenhuma requisição externa. Use máscaras apenas com ícones monocromáticos: a máscara mantém a forma e descarta as cores do próprio ícone. Para ícones multicoloridos, use background-image.

4. React e outros frameworks com JSX

O JSX exige atributos em camelCase (strokeWidth, não stroke-width) e repassa as props. A aba React do painel de cada ícone gera um componente pronto:

export function HouseIcon(props) {
  return (
    <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em"
         viewBox="0 0 24 24" {...props}>
      <path fill="none" stroke="currentColor" strokeWidth={2} d="…" />
    </svg>
  );
}

// Uso
<HouseIcon className="text-blue-600" style={{ fontSize: 20 }} aria-hidden="true" />

Como o tamanho é 1em, o ícone acompanha o font-size, e como a cor é currentColor, classes utilitárias como text-* do Tailwind mudam a cor. Mantenha um arquivo por ícone, ou agrupe os ícones em um módulo, para que o bundler descarte os que você não importa (tree-shaking). O mesmo componente funciona no Preact, e a aba Solid traz a variante para Solid.

5. Vue e Svelte

No Vue, salve o ícone como um componente de arquivo único. Atributos passados, como class, vão para o <svg> raiz:

<!-- HouseIcon.vue -->
<template>
  <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24">
    <path fill="none" stroke="currentColor" stroke-width="2" d="…" />
  </svg>
</template>

O Svelte funciona do mesmo jeito: um arquivo .svelte com a marcação SVG e {...$$props} no elemento raiz. As duas opções estão disponíveis como abas no painel do ícone.

Tamanho e cor

• Use 1em para o tamanho. Com largura e altura em 1em, o ícone acompanha o texto ao lado. Mude o font-size para redimensioná-lo.
• Mantenha o viewBox. O viewBox define o sistema de coordenadas do desenho. Sem ele, o dimensionamento quebra; redimensione pela largura e pela altura.
• Respeite a grade. Ícones desenhados em uma grade de 24px ficam mais nítidos em 24px, 48px ou outros múltiplos. Em 18px ou 20px, traços finos podem parecer um pouco borrados.
• Mude a cor de ícones monocromáticos com color. Com currentColor, uma única regra CSS cuida dos estados normal, hover e modo escuro.
• Ícones multicoloridos mantêm a paleta. Emojis, bandeiras e logotipos têm as cores embutidas. Só mude as cores quando a licença permitir modificações, e nunca altere logotipos de marcas.

Acessibilidade

Decida se o ícone transmite significado. Ícones decorativos ao lado de um texto devem ficar ocultos para leitores de tela, e ícones que aparecem sozinhos precisam de uma alternativa em texto:

<!-- Decorativo: o botão já tem um texto -->
<button><svg aria-hidden="true" …>…</svg> Salvar</button>

<!-- Botão só com ícone: rotule o botão e oculte o ícone -->
<button aria-label="Fechar"><svg aria-hidden="true" …>…</svg></button>

<!-- Imagem com significado -->
<img src="…/triangle-alert.svg" alt="Aviso">

Verifique também o contraste: pela WCAG 2.2, ícones que transmitem informação precisam de uma relação de contraste de pelo menos 3:1 com o fundo.

Qual método usar?

Pronto para começar? Pesquise em todas as coleções ou explore coleções populares como Lucide, Tabler Icons e Material Design Icons. Antes de publicar, confira a licença da coleção; o guia de licenças de ícones explica o que cada uma exige.