Iconos para Tailwind CSS

Instalación

El plugin viene incluido en el paquete principal como glyphfox/tailwind. Tailwind CSS es una peer dependency opcional, y el mismo plugin funciona con Tailwind CSS v3 y v4.

npm install glyphfox

Con Tailwind CSS v4, registra el plugin en la hoja de estilos que importa Tailwind:

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

Con Tailwind CSS v3, añádelo al array plugins de tu archivo de configuración:

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

No necesitas nada más: ni archivos de fuentes, ni sprite, ni JavaScript en el navegador. El plugin lee los datos de los iconos en tiempo de compilación y escribe una regla CSS por cada clase de icono que encuentra en tus archivos fuente.

Tus primeras clases de icono

Una clase de icono es el prefijo gf- seguido del nombre del icono. Ponla en un elemento en línea vacío, normalmente un span. La clase convierte el elemento en un bloque en línea de 1em por 1em, lo alinea con la línea base del texto y lo pinta con el color de texto actual.

<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 la caja es un cuadrado de 1em, las utilidades de tamaño de texto determinan el tamaño del icono: text-sm da un icono de 14 píxeles y text-2xl, uno de 24 píxeles. Dentro de un botón, el icono sigue al texto del botón sin clases adicionales, lo que mantiene proporcionados el icono y la etiqueta en todos los breakpoints.

El color viene de color, así que se aplican las utilidades text-*, las variantes hover: y dark: y los colores heredados. Internamente, el icono es el color de fondo del elemento, definido como currentColor y visto a través de una máscara con la forma del icono. Por eso las utilidades de color de texto lo colorean y opacity-* lo atenúa como a cualquier otro elemento.

Funciona cualquier nombre del explorador de iconos, por ejemplo arrow-right, settings o bell-ring. Una clase con un nombre que no existe no genera nada de CSS, así que un nombre mal escrito aparece como un espacio vacío y no como un estilo roto.

Estilos, esquinas y peso tras la barra

Los tres ejes que tiene cada icono de glyphfox se escriben después de una barra, unidos con guiones. Cada combinación es una máscara propia, renderizada a partir de la misma geometría que usan los componentes.

<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 rellena las formas cerradas y recorta las líneas interiores como espacio negativo. duotone mantiene el contorno y añade la segunda capa con su propia opacidad. outline es el valor predeterminado.
• sharp cambia a uniones en inglete y extremos cuadrados; round es el valor predeterminado.
• Los valores de w1 a w3 definen el peso del trazo en la cuadrícula de 24, con pasos tan finos como quieras: w1.5, w2.25.

Una máscara aporta forma y transparencia, no color. Por eso la capa duotone se ve como una zona más clara del mismo color y no como un segundo color. Cuando necesites dos colores, renderiza el icono como SVG en línea con un componente o con toSvg y define secondaryColor.

Insignias y fusiones

La sintaxis de nombres que comparten todos los paquetes de glyphfox también funciona en las clases: file+check añade una insignia de modificador, @tl, @tr, @bl o @br la mueve a una esquina, y cloud&lock fusiona dos o más iconos en uno. Tailwind CSS v4 solo acepta + y & dentro de corchetes, así que escribe estas especificaciones como valores arbitrarios:

<!-- 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>

Después de la barra, un token de esquina (tl, tr, bl, br) coloca la insignia y un token de disposición (overlap, side, stack, grid, orbit, badge, inside) organiza una fusión. Se combinan con los ejes: gf-[cloud&lock]/side-solid es una fusión con los iconos uno al lado del otro en estilo solid.

En v3, todos los pares name+modifier están disponibles de entrada en la forma corta. Las fusiones en forma corta hay que declararlas con la opción combos, que se muestra más abajo; la forma con corchetes no necesita configuración en ninguna de las dos versiones.

Clases de animación

El plugin también añade seis utilidades de animación: gf-spin, gf-pulse, gf-pop, gf-wiggle, gf-bounce y gf-shake. Usan los mismos tiempos que los estados vivos de los componentes. Spin y pulse se repiten en bucle; las demás se reproducen una vez al aplicar la clase.

<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>

Estas clases mueven el elemento completo con transform y opacity. No pueden dibujar los trazos uno a uno, por eso no existe una clase draw, y tampoco pueden transformar un icono en otro. Para eso, usa SVG en línea: la guía de iconos animados explica ambas cosas. Todas las clases de animación se desactivan solas con prefers-reduced-motion: reduce.

Opciones del plugin

El plugin acepta seis opciones. En Tailwind CSS v4, pásalas en un bloque después de @plugin; en v3, llama al plugin como una función.

@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'],
    }),
  ],
};

Referencia de clases

Aquí las clases sustituyen a las props. Estos son todos los tokens que entiende el plugin; la sintaxis completa de nombres se describe en la documentación.

Accesibilidad

Un icono de máscara es un elemento vacío con un fondo. Las tecnologías de apoyo no perciben nada, lo cual es correcto para un icono decorativo junto a una etiqueta: añade aria-hidden="true" para que se omita el elemento vacío. Cuando el icono es el único contenido de un control, el propio control necesita un nombre:

<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>

En el modo de alto contraste de Windows, el navegador sustituye los colores de fondo por colores del sistema, y un icono de máscara puede fundirse con la página. Asigna una clase común a los span de tus iconos y restaura el color en ese modo:

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

La guía de accesibilidad trata las etiquetas, el contraste y el movimiento para todas las formas de renderizar los iconos de glyphfox.

Qué añade a tu CSS

Tailwind solo genera reglas para las clases que encuentra en tus archivos, y el plugin sigue el mismo criterio: un icono que nunca escribes no cuesta nada. Cada clase de icono que sí usas incrusta su máscara como un pequeño data URI, de unos 300 bytes para una forma sencilla como home o file y de casi 1 KB para una detallada como settings, antes de la compresión. Cada variante de estilo, peso o esquinas de un mismo icono es una regla aparte con su propio data URI.

Para una página con unas pocas decenas de iconos, eso supone unos pocos kilobytes de CSS y ninguna solicitud. Si usas cientos de iconos en cada página, o muchas variantes de cada uno, compáralo con un sprite SVG, que el navegador guarda en caché como un solo archivo.

Errores comunes

Nombres de clase construidos por partes

Tailwind detecta las clases buscando cadenas completas en tus archivos. `gf-${name}` nunca aparece completo, así que no se genera CSS. Asocia los valores a nombres de clase completos, como { saved: 'gf-[file+check]', error: 'gf-[file+alert]' }, o añade los nombres que necesites a una safelist.

Signo más y ampersand sin corchetes en v4

En Tailwind CSS v4, gf-file+check y gf-cloud&lock no son candidatos de clase válidos y no generan nada. Usa gf-[file+check] y gf-[cloud&lock], que funcionan en ambas versiones.

Utilidades de ancho que chocan con el tamaño del icono

La clase de icono asigna a width y height el valor de la opción size. Un size-6 o un w-6 en el mismo elemento definen las mismas propiedades, y cuál gana depende del orden de las reglas en el CSS generado. Ajusta el tamaño de los iconos con utilidades de texto o cambia una sola vez la opción size.

Dos colores

Una máscara pinta un solo color. /duotone da una segunda capa translúcida del mismo color; para un segundo color real, renderiza SVG en línea con secondaryColor.

Contenido dentro del elemento

El icono es el fondo del elemento. El texto o los elementos hijos que contenga se renderizan encima del icono, y una utilidad bg-* sustituye el color del icono. Deja vacíos los elementos de icono.

Animaciones en elementos ocultos

Una clase gf-pop o gf-shake se reproduce una vez cuando se renderiza el elemento. Si se renderiza mientras está oculto, la animación termina antes de que nadie la vea. Añade la clase en el momento en que se produce el cambio, o usa un componente con trigger="state".