Ícones Tailwind CSS

Instalação

O plugin vem dentro do pacote principal como glyphfox/tailwind. O Tailwind CSS é uma peer dependency opcional, e o mesmo plugin funciona com o Tailwind CSS v3 e v4.

npm install glyphfox

No Tailwind CSS v4, registre o plugin na folha de estilo que importa o Tailwind:

@import "tailwindcss";
@plugin "glyphfox/tailwind";

No Tailwind CSS v3, adicione o plugin ao array plugins do seu arquivo de configuração:

module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}'],
  plugins: [require('glyphfox/tailwind')],
};

Não precisa de mais nada: nenhum arquivo de fonte, nenhum sprite e nenhum JavaScript no navegador. O plugin lê os dados dos ícones durante o build e gera uma regra CSS para cada classe de ícone que encontra nos seus arquivos de código-fonte.

Suas primeiras classes de ícone

Uma classe de ícone é o prefixo gf- seguido do nome do ícone. Coloque a classe em um elemento inline vazio, normalmente um span. Ela transforma o elemento em um bloco inline de 1em por 1em, alinhado à linha de base do texto, e o pinta com a cor atual do texto.

<button class="inline-flex items-center gap-2 text-sm text-zinc-200">
  <span class="gf-download" aria-hidden="true"></span>
  Download
</button>

<span class="gf-home text-2xl text-orange-500" aria-hidden="true"></span>
<span class="gf-heart text-4xl text-rose-500 opacity-80" aria-hidden="true"></span>

Como a caixa é um quadrado de 1em, os utilitários de tamanho de texto definem o tamanho do ícone: text-sm gera um ícone de 14 pixels, e text-2xl, um de 24 pixels. Dentro de um botão, o ícone acompanha o texto do botão sem classes extras, o que mantém ícone e rótulo proporcionais em todos os breakpoints.

A cor vem de color, então os utilitários text-*, as variantes hover: e dark: e as cores herdadas funcionam normalmente. Por baixo dos panos, o ícone é a cor de fundo do elemento, definida como currentColor e vista através de uma máscara com o formato do ícone. É por isso que os utilitários de cor de texto colorem o ícone e o opacity-* o deixa mais transparente, como acontece com qualquer outro elemento.

Qualquer nome do explorador de ícones funciona, por exemplo arrow-right, settings ou bell-ring. Uma classe com um nome que não existe não gera CSS nenhum, então um erro de digitação aparece como um espaço vazio, e não como um estilo quebrado.

Estilos, cantos e peso depois da barra

Os três eixos que todo ícone do glyphfox tem vão depois de uma barra, unidos por hífens. Cada combinação é uma máscara própria, renderizada a partir da mesma geometria que os componentes usam.

<span class="gf-folder/solid"></span>
<span class="gf-folder/duotone"></span>
<span class="gf-search/sharp"></span>
<span class="gf-search/w1.5"></span>
<span class="gf-heart/duotone-sharp-w2.5"></span>

• solid preenche as formas fechadas e recorta as linhas internas como espaço negativo. duotone mantém o contorno e adiciona a segunda camada com opacidade própria. outline é o padrão.
• sharp muda para junções em ângulo e pontas quadradas; round é o padrão.
• w1 a w3 definem o peso do traço na grade de 24, em passos tão finos quanto você quiser: w1.5, w2.25.

Uma máscara carrega forma e transparência, não cor. Por isso, a camada duotone aparece como uma área mais clara da mesma cor, e não como uma segunda cor. Quando precisar de duas cores, renderize o ícone como SVG inline com um componente ou com toSvg e defina secondaryColor.

Selos e fusões

A sintaxe de nomes compartilhada por todos os pacotes do glyphfox também funciona nas classes: file+check adiciona um selo modificador, @tl, @tr, @bl ou @br move o selo para um canto, e cloud&lock funde dois ou mais ícones em um só. O Tailwind CSS v4 só aceita + e & dentro de colchetes, então escreva essas specs como valores arbitrários:

<!-- Tailwind CSS v4 and v3 -->
<span class="gf-[file+check]"></span>
<span class="gf-[file+check]/tr"></span>
<span class="gf-[cloud&lock]"></span>
<span class="gf-[cloud&lock]/side"></span>
<span class="gf-[shield&heart]/inside"></span>

<!-- Tailwind CSS v4 also accepts the layout inside the brackets -->
<span class="gf-[cloud&lock:side]"></span>

<!-- Tailwind CSS v3 also accepts the short form -->
<span class="gf-file+check"></span>
<span class="gf-file+check/tr"></span>

Depois da barra, um token de canto (tl, tr, bl, br) posiciona o selo e um token de layout (overlap, side, stack, grid, orbit, badge, inside) organiza uma fusão. Eles se combinam com os eixos: gf-[cloud&lock]/side-solid é uma fusão lado a lado no estilo sólido.

No v3, todo par name+modifier já vem disponível na forma curta. Fusões na forma curta precisam ser listadas com a opção combos, mostrada abaixo; a forma com colchetes não precisa de configuração em nenhuma das versões.

Classes de animação

O plugin também adiciona seis utilitários de animação: gf-spin, gf-pulse, gf-pop, gf-wiggle, gf-bounce e gf-shake. Eles usam a mesma temporização dos estados vivos dos componentes. Spin e pulse repetem em loop; os demais tocam uma vez quando a classe é aplicada.

<span class="gf-loader-circle gf-spin text-xl" aria-hidden="true"></span>
<span class="gf-bell gf-shake text-xl" aria-hidden="true"></span>

<!-- replay on hover with a variant -->
<span class="gf-heart text-xl hover:gf-pop" aria-hidden="true"></span>

Essas classes movem o elemento inteiro com transform e opacity. Elas não conseguem desenhar os traços um por um, por isso não existe uma classe draw, nem conseguem transformar um ícone em outro. Para isso, use SVG inline: o guia de ícones animados cobre os dois casos. Toda classe de animação se desliga sozinha com prefers-reduced-motion: reduce.

Opções do plugin

O plugin aceita seis opções. No Tailwind CSS v4, passe as opções em um bloco depois de @plugin; no v3, chame o plugin como uma função.

@import "tailwindcss";
@plugin "glyphfox/tailwind" {
  prefix: icon;
  variant: duotone;
  weight: 1.5;
}

const glyphfox = require('glyphfox/tailwind');

module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  plugins: [
    glyphfox({
      prefix: 'icon',            // icon-home, icon-spin
      size: '1.25em',            // box size, 1em by default
      corners: 'sharp',          // default axes for every class
      weight: 1.75,
      combos: ['cloud&lock', 'file+check@tr'],
    }),
  ],
};

Referência de classes

Aqui, as classes substituem as props. Estes são todos os tokens que o plugin entende; a sintaxe de nomes completa está descrita na documentação.

Acessibilidade

Um ícone de máscara é um elemento vazio com um fundo. As tecnologias assistivas não enxergam nada, o que é o comportamento certo para um ícone decorativo ao lado de um rótulo: adicione aria-hidden="true" para que o elemento vazio seja ignorado. Quando o ícone é o único conteúdo de um controle, o controle precisa de um nome próprio:

<button type="button" class="p-2 text-zinc-300 hover:text-white">
  <span class="gf-settings text-xl" aria-hidden="true"></span>
  <span class="sr-only">Settings</span>
</button>

No modo de alto contraste do Windows, o navegador troca as cores de fundo pelas cores do sistema, e um ícone de máscara pode sumir na página. Dê uma classe em comum aos spans dos seus ícones e restaure a cor nesse modo:

@media (forced-colors: active) {
  .icon {
    forced-color-adjust: none;
    background-color: CanvasText;
  }
}

O guia de acessibilidade trata de rótulos, contraste e movimento em todas as formas de renderizar os ícones do glyphfox.

O que o plugin adiciona ao seu CSS

O Tailwind só gera regras para as classes que encontra nos seus arquivos, e o plugin segue a mesma lógica: um ícone que você nunca escreve não custa nada. Cada classe de ícone que você usa embute a máscara como um pequeno data URI, com cerca de 300 bytes para uma forma simples como home ou file e perto de 1 KB para uma mais detalhada como settings, antes da compressão. Cada variante de estilo, peso ou cantos do mesmo ícone é uma regra separada, com o próprio data URI.

Para uma página com algumas dezenas de ícones, isso dá alguns kilobytes de CSS e nenhuma requisição. Se você usa centenas de ícones em todas as páginas, ou muitas variantes de cada um, compare com um sprite SVG, que o navegador guarda em cache como um único arquivo.

Armadilhas comuns

Nomes de classe montados em partes

O Tailwind encontra as classes procurando strings completas nos seus arquivos. `gf-${name}` nunca aparece por inteiro, então nenhum CSS é gerado. Mapeie os valores para nomes de classe completos, como { saved: 'gf-[file+check]', error: 'gf-[file+alert]' }, ou adicione a uma safelist os nomes de que você precisa.

Sinal de mais ou e comercial sem colchetes no v4

No Tailwind CSS v4, gf-file+check e gf-cloud&lock não são candidatos a classe válidos e não geram nada. Use gf-[file+check] e gf-[cloud&lock], que funcionam nas duas versões.

Utilitários de largura em conflito com o tamanho do ícone

A classe de ícone define width e height com o valor da opção size. Um size-6 ou w-6 no mesmo elemento define as mesmas propriedades, e qual delas vence depende da ordem das regras no CSS gerado. Defina o tamanho dos ícones com utilitários de texto, ou altere a opção size uma única vez.

Duas cores

Uma máscara pinta uma única cor. /duotone gera uma segunda camada translúcida da mesma cor; para ter de fato uma segunda cor, renderize SVG inline com secondaryColor.

Conteúdo dentro do elemento

O ícone é o fundo do elemento. Texto ou filhos dentro dele são renderizados por cima do ícone, e um utilitário bg-* substitui a cor do ícone. Mantenha os elementos de ícone vazios.

Animações em elementos ocultos

Uma classe gf-pop ou gf-shake toca uma vez quando o elemento é renderizado. Se ele for renderizado enquanto está oculto, a animação termina antes que alguém a veja. Adicione a classe no momento da mudança, ou use um componente com trigger="state".