Tailwind-CSS-Icons

Installation

Das Plugin ist als glyphfox/tailwind im Hauptpaket enthalten. Tailwind CSS ist eine optionale Peer-Dependency, und dasselbe Plugin funktioniert mit Tailwind CSS v3 und v4.

npm install glyphfox

In Tailwind CSS v4 registrieren Sie das Plugin in dem Stylesheet, das Tailwind importiert:

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

In Tailwind CSS v3 fügen Sie es dem Array plugins Ihrer Konfigurationsdatei hinzu:

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

Mehr ist nicht nötig: keine Schriftdateien, kein Sprite und kein JavaScript im Browser. Das Plugin liest die Icon-Daten zur Build-Zeit und schreibt eine CSS-Regel für jede Icon-Klasse, die es in Ihren Quelldateien findet.

Ihre ersten Icon-Klassen

Eine Icon-Klasse besteht aus dem Präfix gf-, gefolgt vom Namen des Icons. Setzen Sie sie auf ein leeres Inline-Element, meist ein span. Die Klasse macht das Element zu einem Inline-Block von 1em mal 1em, richtet es an der Grundlinie des Textes aus und füllt es mit der aktuellen Textfarbe.

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

Da die Box ein Quadrat mit 1em Kantenlänge ist, bestimmen die Utilities für die Textgröße auch die Größe des Icons: text-sm ergibt ein 14 Pixel großes Icon, text-2xl ein 24 Pixel großes. In einem Button folgt das Icon ohne zusätzliche Klassen dem Button-Text, sodass Icon und Beschriftung an jedem Breakpoint im richtigen Verhältnis bleiben.

Die Farbe stammt aus color, daher greifen die text-*-Utilities, die Varianten hover: und dark: sowie geerbte Farben. Technisch gesehen ist das Icon die Hintergrundfarbe des Elements, gesetzt auf currentColor und sichtbar durch eine Maske in Form des Icons. Deshalb färben es die Utilities für die Textfarbe, und opacity-* verringert wie bei jedem anderen Element seine Deckkraft.

Jeder Name aus dem Icon-Browser funktioniert, zum Beispiel arrow-right, settings oder bell-ring. Eine Klasse mit einem Namen, den es nicht gibt, erzeugt überhaupt kein CSS. Ein Tippfehler zeigt sich daher als leere Stelle und nicht als fehlerhafte Darstellung.

Stile, Ecken und Strichstärke nach dem Schrägstrich

Die drei Achsen, die jedes glyphfox-Icon hat, stehen nach einem Schrägstrich und werden mit Bindestrichen verbunden. Jede Kombination ist eine eigene Maske, gerendert aus derselben Geometrie, die auch die Komponenten verwenden.

<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 füllt die geschlossenen Formen und spart die inneren Linien als Negativraum aus. duotone behält die Kontur bei und ergänzt die zweite Ebene mit eigener Deckkraft. outline ist der Standard.
• sharp wechselt zu spitzen Linienverbindungen und eckigen Linienenden; round ist der Standard.
• w1 bis w3 legen die Strichstärke im 24er-Raster fest, in beliebig feinen Schritten: w1.5, w2.25.

Eine Maske überträgt Form und Transparenz, aber keine Farbe. Die Duotone-Ebene erscheint daher als hellere Fläche derselben Farbe, nicht als zweite Farbe. Wenn Sie zwei Farben brauchen, rendern Sie das Icon mit einer Komponente oder toSvg als Inline-SVG und setzen Sie secondaryColor.

Badges und Fusionen

Die Namenssyntax, die alle glyphfox-Pakete teilen, funktioniert auch in Klassen: file+check fügt ein Modifier-Badge hinzu, @tl, @tr, @bl oder @br verschiebt es in eine Ecke, und cloud&lock verschmilzt zwei oder mehr Icons zu einem. Da Tailwind CSS v4 + und & nur in eckigen Klammern akzeptiert, schreiben Sie diese Angaben als Arbitrary Values:

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

Nach dem Schrägstrich platziert ein Ecken-Token (tl, tr, bl, br) das Badge, und ein Layout-Token (overlap, side, stack, grid, orbit, badge, inside) ordnet eine Fusion an. Beide lassen sich mit den Achsen kombinieren: gf-[cloud&lock]/side-solid ist eine Fusion mit nebeneinanderstehenden Icons im Solid-Stil.

In v3 ist jedes Paar name+modifier von Haus aus in der Kurzform verfügbar. Fusionen in Kurzform müssen Sie über die weiter unten gezeigte Option combos auflisten; die Schreibweise mit Klammern kommt in beiden Versionen ohne Konfiguration aus.

Animationsklassen

Außerdem ergänzt das Plugin sechs Animations-Utilities: gf-spin, gf-pulse, gf-pop, gf-wiggle, gf-bounce und gf-shake. Sie verwenden dasselbe Timing wie die lebendigen Zustände der Komponenten. Spin und Pulse wiederholen sich endlos; die übrigen spielen einmal ab, sobald die Klasse gesetzt wird.

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

Diese Klassen bewegen das gesamte Element mit transform und opacity. Sie können Striche nicht einzeln nachzeichnen, daher gibt es keine Klasse draw, und sie können kein Icon in ein anderes morphen. Dafür brauchen Sie Inline-SVG: Der Leitfaden zu animierten Icons behandelt beides. Jede Animationsklasse schaltet sich bei prefers-reduced-motion: reduce selbst ab.

Plugin-Optionen

Das Plugin kennt sechs Optionen. In Tailwind CSS v4 übergeben Sie sie in einem Block nach @plugin; in v3 rufen Sie das Plugin als Funktion auf.

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

Klassenreferenz

Hier ersetzen Klassen die Props. Das sind alle Token, die das Plugin versteht; die vollständige Namenssyntax ist in der Dokumentation beschrieben.

Barrierefreiheit

Ein Masken-Icon ist ein leeres Element mit einem Hintergrund. Assistive Technologien erkennen darin nichts, was für ein dekoratives Icon neben einer Beschriftung genau richtig ist: Ergänzen Sie aria-hidden="true", damit das leere Element übersprungen wird. Ist das Icon der einzige Inhalt eines Bedienelements, braucht dieses einen eigenen Namen:

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

Im Hochkontrastmodus von Windows ersetzt der Browser Hintergrundfarben durch Systemfarben, und ein Masken-Icon kann im Hintergrund der Seite verschwinden. Geben Sie Ihren Icon-Spans eine gemeinsame Klasse und stellen Sie die Farbe in diesem Modus wieder her:

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

Der Leitfaden zur Barrierefreiheit behandelt Beschriftungen, Kontrast und Bewegung für jede Art, glyphfox-Icons zu rendern.

Was zu Ihrem CSS hinzukommt

Tailwind erzeugt nur Regeln für die Klassen, die es in Ihren Dateien findet, und das Plugin folgt demselben Prinzip: Ein Icon, das Sie nie schreiben, kostet nichts. Jede Icon-Klasse, die Sie tatsächlich verwenden, bettet ihre Maske als kleine Data-URI ein, etwa 300 Byte für eine einfache Form wie home oder file und knapp 1 KB für eine detailreiche wie settings, jeweils vor der Komprimierung. Jede Variante desselben Icons in Stil, Strichstärke oder Ecken ist eine eigene Regel mit eigener Data-URI.

Bei einer Seite mit ein paar Dutzend Icons sind das einige Kilobyte CSS und keine einzige Anfrage. Wenn Sie auf jeder Seite Hunderte Icons verwenden oder von jedem viele Varianten, ziehen Sie zum Vergleich ein SVG-Sprite heran, das der Browser als eine einzige Datei im Cache hält.

Stolperfallen

Aus Teilen zusammengesetzte Klassennamen

Tailwind findet Klassen, indem es Ihre Dateien nach vollständigen Zeichenketten durchsucht. `gf-${name}` taucht nie vollständig auf, also wird kein CSS erzeugt. Ordnen Sie Werte vollständigen Klassennamen zu, etwa { saved: 'gf-[file+check]', error: 'gf-[file+alert]' }, oder nehmen Sie die benötigten Namen in eine Safelist auf.

Plus- und Et-Zeichen ohne Klammern in v4

In Tailwind CSS v4 sind gf-file+check und gf-cloud&lock keine gültigen Klassenkandidaten und erzeugen nichts. Verwenden Sie gf-[file+check] und gf-[cloud&lock], die in beiden Versionen funktionieren.

Breiten-Utilities, die mit der Icon-Größe konkurrieren

Die Icon-Klasse setzt width und height auf den Wert der Option size. Ein size-6 oder w-6 am selben Element setzt dieselben Eigenschaften, und welche Angabe gewinnt, hängt von der Reihenfolge der Regeln im generierten CSS ab. Steuern Sie die Größe von Icons über Text-Utilities, oder ändern Sie einmalig die Option size.

Zwei Farben

Eine Maske malt nur eine einzige Farbe. /duotone ergibt eine durchscheinende zweite Ebene derselben Farbe; für eine echte zweite Farbe rendern Sie Inline-SVG mit secondaryColor.

Inhalt im Element

Das Icon ist der Hintergrund des Elements. Text oder Kindelemente darin werden über dem Icon dargestellt, und eine bg-*-Utility ersetzt die Farbe des Icons. Lassen Sie Icon-Elemente leer.

Animationen an ausgeblendeten Elementen

Eine Klasse gf-pop oder gf-shake läuft einmal ab, sobald das Element gerendert wird. Wird es gerendert, während es ausgeblendet ist, ist die Animation vorbei, bevor sie jemand sieht. Setzen Sie die Klasse erst, wenn die Änderung eintritt, oder verwenden Sie eine Komponente mit trigger="state".