Icônes Tailwind CSS

Installation

Le plugin est livré dans le paquet principal, sous glyphfox/tailwind. Tailwind CSS est une dépendance peer facultative, et le même plugin fonctionne avec Tailwind CSS v3 et v4.

npm install glyphfox

Avec Tailwind CSS v4, déclarez le plugin dans la feuille de style qui importe Tailwind :

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

Avec Tailwind CSS v3, ajoutez-le au tableau plugins de votre fichier de configuration :

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

Rien d'autre n'est nécessaire : ni fichier de police, ni sprite, ni JavaScript dans le navigateur. Le plugin lit les données des icônes au moment du build et génère une règle CSS pour chaque classe d'icône qu'il trouve dans vos fichiers source.

Vos premières classes d'icônes

Une classe d'icône se compose du préfixe gf- suivi du nom de l'icône. Placez-la sur un élément en ligne vide, généralement un span. La classe fait de l'élément un bloc en ligne de 1em sur 1em, l'aligne sur la ligne de base du texte et le peint dans la couleur actuelle du texte.

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

Comme la boîte est un carré de 1em, ce sont les utilitaires de taille de texte qui dimensionnent l'icône : text-sm donne une icône de 14 pixels, text-2xl une icône de 24 pixels. Dans un bouton, l'icône suit le texte du bouton sans classe supplémentaire, ce qui préserve les proportions entre l'icône et le libellé à chaque point de rupture.

La couleur provient de color : les utilitaires text-*, les variantes hover: et dark: ainsi que les couleurs héritées s'appliquent donc toutes. Sous le capot, l'icône est la couleur d'arrière-plan de l'élément, définie sur currentColor et vue à travers un masque qui reprend la forme de l'icône. C'est pourquoi les utilitaires de couleur de texte la colorent et opacity-* l'estompe, comme n'importe quel autre élément.

Tous les noms de l'explorateur d'icônes fonctionnent, par exemple arrow-right, settings ou bell-ring. Une classe dont le nom n'existe pas ne produit aucun CSS : une faute de frappe se traduit donc par un espace vide plutôt que par un style cassé.

Styles, coins et épaisseur après la barre oblique

Les trois axes communs à toutes les icônes glyphfox s'écrivent après une barre oblique, séparés par des tirets. Chaque combinaison forme un masque distinct, rendu à partir de la même géométrie que celle des composants.

<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 remplit les formes fermées et découpe les lignes intérieures en négatif. duotone conserve le contour et ajoute le second calque avec sa propre opacité. outline est la valeur par défaut.
• sharp passe à des jointures en onglet et à des extrémités carrées ; round est la valeur par défaut.
• w1 à w3 définissent l'épaisseur du trait sur la grille de 24, par incréments aussi fins que vous le souhaitez : w1.5, w2.25.

Un masque véhicule la forme et la transparence, pas la couleur. Le calque duotone apparaît donc comme une zone plus claire de la même couleur, et non comme une seconde couleur. Si vous avez besoin de deux couleurs, affichez l'icône en SVG inline avec un composant ou toSvg, puis définissez secondaryColor.

Badges et fusions

La syntaxe de noms commune à tous les paquets glyphfox fonctionne aussi dans les classes : file+check ajoute un badge de modificateur, @tl, @tr, @bl ou @br le déplace vers un coin, et cloud&lock fusionne deux icônes ou plus en une seule. Comme Tailwind CSS v4 n'accepte + et & qu'entre crochets, écrivez ces spécifications sous forme de valeurs arbitraires :

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

Après la barre oblique, un jeton de coin (tl, tr, bl, br) positionne le badge et un jeton de disposition (overlap, side, stack, grid, orbit, badge, inside) organise une fusion. Ils se combinent avec les axes : gf-[cloud&lock]/side-solid est une fusion côte à côte dans le style solid.

En v3, chaque paire name+modifier est disponible d'emblée sous la forme courte. Les fusions en forme courte doivent être listées avec l'option combos présentée plus bas ; la forme entre crochets ne demande aucune configuration, quelle que soit la version.

Classes d'animation

Le plugin ajoute aussi six utilitaires d'animation : gf-spin, gf-pulse, gf-pop, gf-wiggle, gf-bounce et gf-shake. Ils reprennent le minutage des états vivants des composants. Spin et pulse s'exécutent en boucle ; les autres se jouent une seule fois, lorsque la classe est appliquée.

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

Ces classes animent l'élément entier avec transform et opacity. Elles ne peuvent pas tracer les traits un par un (il n'existe donc pas de classe draw), ni transformer une icône en une autre. Pour cela, passez au SVG inline : le guide des icônes animées couvre ces deux cas. Chaque classe d'animation se désactive d'elle-même dès que prefers-reduced-motion: reduce est actif.

Options du plugin

Le plugin accepte six options. Avec Tailwind CSS v4, passez-les dans un bloc après @plugin ; en v3, appelez le plugin comme une fonction.

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

Référence des classes

Ici, les classes remplacent les props. Voici tous les jetons que le plugin comprend ; la syntaxe complète des noms est décrite dans la documentation.

Accessibilité

Une icône en masque est un élément vide doté d'un arrière-plan. Les technologies d'assistance n'y voient rien, ce qui convient à une icône décorative placée à côté d'un libellé : ajoutez aria-hidden="true" pour que l'élément vide soit ignoré. Lorsque l'icône est le seul contenu d'un contrôle, celui-ci a besoin de son propre nom :

<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 mode Contraste élevé de Windows, le navigateur remplace les couleurs d'arrière-plan par des couleurs système, et une icône en masque peut se fondre dans la page. Attribuez une classe commune aux éléments span de vos icônes et rétablissez la couleur dans ce mode :

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

Le guide d'accessibilité traite des libellés, du contraste et du mouvement pour toutes les façons d'afficher les icônes glyphfox.

Ce que le plugin ajoute à votre CSS

Tailwind ne génère des règles que pour les classes qu'il trouve dans vos fichiers, et le plugin suit le même principe : une icône que vous n'écrivez jamais ne coûte rien. Chaque classe d'icône que vous utilisez réellement intègre son masque sous forme de petite data URI : environ 300 octets pour une forme simple comme home ou file, et près de 1 Ko pour une forme détaillée comme settings, avant compression. Toute variante de style, d'épaisseur ou de coins d'une même icône constitue une règle distincte, avec sa propre data URI.

Pour une page comportant quelques dizaines d'icônes, cela représente quelques kilooctets de CSS et aucune requête. Si vous utilisez des centaines d'icônes sur chaque page, ou de nombreuses variantes de chacune, comparez avec un sprite SVG, que le navigateur met en cache sous la forme d'un seul fichier.

Pièges courants

Noms de classes assemblés par morceaux

Tailwind détecte les classes en recherchant des chaînes complètes dans vos fichiers. `gf-${name}` n'y apparaît jamais en entier, donc aucun CSS n'est généré. Associez vos valeurs à des noms de classes complets, par exemple { saved: 'gf-[file+check]', error: 'gf-[file+alert]' }, ou ajoutez les noms dont vous avez besoin à une safelist.

Plus et esperluette sans crochets en v4

Dans Tailwind CSS v4, gf-file+check et gf-cloud&lock ne sont pas des candidats de classe valides et ne produisent rien. Utilisez gf-[file+check] et gf-[cloud&lock], qui fonctionnent dans les deux versions.

Utilitaires de largeur en conflit avec la taille de l'icône

La classe d'icône règle width et height sur la valeur de l'option size. Un size-6 ou un w-6 sur le même élément définit les mêmes propriétés, et c'est l'ordre des règles dans le CSS généré qui décide laquelle l'emporte. Dimensionnez les icônes avec les utilitaires de texte, ou modifiez une fois pour toutes l'option size.

Deux couleurs

Un masque ne peint qu'une seule couleur. /duotone donne un second calque translucide de la même couleur ; pour une vraie seconde couleur, affichez du SVG inline avec secondaryColor.

Contenu à l'intérieur de l'élément

L'icône est l'arrière-plan de l'élément. Le texte ou les enfants qu'il contient s'affichent par-dessus l'icône, et un utilitaire bg-* remplace la couleur de l'icône. Laissez les éléments d'icône vides.

Animations sur des éléments masqués

Une classe gf-pop ou gf-shake se joue une fois, au rendu de l'élément. Si l'élément est rendu alors qu'il est masqué, l'animation se termine avant que quiconque ne la voie. Ajoutez la classe au moment où le changement se produit, ou utilisez un composant avec trigger="state".