React-Icons

Installation

Die React-Komponenten befinden sich im Hauptpaket glyphfox unter dem Einstiegspunkt glyphfox/react. React ist eine optionale Peer-Dependency: Das Paket funktioniert mit React 16.8 und neuer, weil es nur Hooks und forwardRef benötigt, und seine Testsuite läuft gegen React 19.

npm install glyphfox

Sie müssen weder ein Stylesheet importieren noch ein Build-Plugin hinzufügen. Das Paket liefert ESM- und CommonJS-Builds mit Typdeklarationen aus, sodass Vite, webpack, Rspack, esbuild und Parcel es ohne weitere Anpassungen verarbeiten.

Ihre ersten Icons rendern

Jedes Icon wird unter seinem Namen in PascalCase mit dem Suffix Icon exportiert: Aus home wird HomeIcon, aus arrow-right wird ArrowRightIcon und aus message-circle wird MessageCircleIcon. Einen Namen finden Sie über die Suche im Icon-Browser; jede Icon-Seite, etwa die zu arrow right, zeigt außerdem die Importzeile.

import { HomeIcon, SearchIcon, BellIcon } from 'glyphfox/react';

export function Toolbar() {
  return (
    <nav className="toolbar">
      <a href="/"><HomeIcon /> Home</a>
      <button type="button" aria-label="Search">
        <SearchIcon />
      </button>
      <BellIcon size={20} />
    </nav>
  );
}

Ohne Props ist ein Icon 24 mal 24 Pixel groß und zeichnet mit stroke="currentColor", übernimmt also die Textfarbe seines Elternelements. Außerdem ist es mit aria-hidden="true" gekennzeichnet, weil die meisten Icons neben einer sichtbaren Beschriftung stehen. Geben Sie ihm einen title, wenn das Icon als Einziges die Bedeutung trägt; der Leitfaden zur Barrierefreiheit beschreibt die passenden Muster.

Größe, Farbe, Strichstärke und Stil

Jedes Icon wird entlang dreier Achsen gerendert: Strichstärke, Ecken und Stil. Es sind ganz normale Props, die wie jeder andere Wert Zuständen, Themes oder Breakpoints folgen können.

import { FolderIcon, SearchIcon, ArrowRightIcon } from 'glyphfox/react';

export function Axes() {
  return (
    <>
      <SearchIcon size={32} color="#ff7a1a" />
      <SearchIcon weight={1} />
      <SearchIcon weight={3} corners="sharp" />
      <SearchIcon size={16} weight={1.5} absoluteWeight />
      <FolderIcon variant="duotone" secondaryColor="#ff7a1a" />
      <FolderIcon variant="solid" />
      <ArrowRightIcon rotate={90} />
      <ArrowRightIcon mirrorRtl />
    </>
  );
}

• size akzeptiert eine Pixelanzahl oder einen beliebigen CSS-Längenwert als String, etwa "1.25em".
• weight reicht von 1 bis 3 auf dem 24er-Raster. Unter 24 Pixeln wird der Strich optisch kompensiert und fällt bei den kleinsten Größen um bis zu 30 Prozent kräftiger aus, sodass ein 16-Pixel-Icon dieselbe Präsenz behält wie eines mit 24 Pixeln. absoluteWeight schaltet das ab und hält den Strich bei genau weight Pixeln.
• variant="duotone" verwendet die von Hand gezeichnete zweite Ebene, sofern das Icon eine hat, andernfalls eine halbtransparente Füllung seiner geschlossenen Formen. variant="solid" füllt die geschlossenen Formen und spart die inneren Linien als Negativraum aus.
• mirrorRtl spiegelt richtungsabhängige Icons, wenn sie innerhalb von dir="rtl" gerendert werden, sodass dasselbe Markup in beiden Leserichtungen funktioniert.

Icons per Name

Wenn das Icon aus Daten stammt, etwa aus einem CMS-Feld, einer Routentabelle oder einer Benutzereinstellung, rendern Sie es mit Icon und einem Namen. Die Prop name versteht die vollständige Namenssyntax, die alle glyphfox-Pakete gemeinsam nutzen, sodass Modifier, Fusionen und Stile mit einem einzigen String funktionieren.

import { Icon } from 'glyphfox/react';

export function MenuItem({ item }) {
  // item.icon could be "settings", "file+check@tr", "cloud&lock:overlap" or "heart/solid"
  return (
    <li>
      <Icon name={item.icon} size={18} />
      {item.label}
    </li>
  );
}

Namen, die nirgends importiert wurden, werden bei Bedarf über einen dynamischen Import geladen. webpack und esbuild teilen ihn in einen kleinen Chunk pro Icon auf, und bis dieser Chunk eintrifft, rendert Icon ein leeres SVG in der richtigen Größe, damit das Layout nicht springt. Ein Vite-Produktionsbuild lässt diesen Import innerhalb von node_modules unangetastet, sodass der Name dort leer bleibt (Details im Leitfaden zum Tree-Shaking). In jedem Bundler ist die Lösung dieselbe: Registrieren Sie die Daten der Namen, die Sie aus Strings rendern, einmal beim Start, dann werden sie synchron gerendert, schon beim ersten Paint und auch auf dem Server:

import { registerIcons } from 'glyphfox/react';
import { iconSettings, iconFile, iconCloud, iconLock } from 'glyphfox';

registerIcons([iconSettings, iconFile, iconCloud, iconLock]);

Die Datenexporte (iconSettings, iconArrowRight ...) stammen aus dem Haupteinstiegspunkt glyphfox und unterliegen wie die Komponenten dem Tree-Shaking: Ein einzelner Import kostet ein paar Hundert Bytes. Wenn Sie eine Komponente wie SettingsIcon importieren, werden ihre Daten ebenfalls registriert.

Modifier und Fusionen

Ein Modifier ist ein kleines Badge in einer Ecke eines beliebigen Icons: plus, minus, check, x, alert, lock, clock, sync, arrow-up, arrow-down oder dot. Das darunterliegende Icon erhält rund um das Badge eine Aussparung, sodass sich die Linien bei keiner Strichstärke berühren.

import { FileIcon, CloudIcon, Fusion } from 'glyphfox/react';

export function Status({ saved, syncing }) {
  return (
    <>
      <FileIcon modifier={saved ? 'check' : undefined} />
      <CloudIcon modifier={syncing ? 'sync' : undefined} modifierCorner="top-right" />
      <Fusion icons={['cloud', 'lock']} layout="overlap" gap={1} />
      <Fusion icons={['shield', 'heart']} layout="inside" />
    </>
  );
}

Fusion verschmilzt 2 bis 10 Icons zu einem neuen Icon, das weiterhin den Icon-Regeln folgt: eine Strichstärke, das 24er-Raster und die Padding-Box. Die Layouts sind overlap, side, stack, grid, orbit, badge und inside; gap legt die Aussparung in Rastereinheiten fest, und mit scale und offsets justieren Sie jeden Teil fein. Fusion akzeptiert alle gemeinsamen Props, sodass ein verschmolzenes Icon wie jedes andere im Duotone-Stil erscheinen, animiert oder beschriftet werden kann.

Morphing und lebendige Zustände

Für Bewegung gibt es drei Werkzeuge. MorphIcon morpht, sobald sich sein name ändert. morphTo lässt jedes beliebige Icon zu einem Ziel morphen, sobald sein trigger auslöst. animate spielt ein Preset ab (draw, pop, wiggle, spin, pulse, bounce oder shake), und zwar beim Mounten, beim Hovern, beim Klicken oder solange active true ist.

import { MorphIcon, MenuIcon, BellIcon, HeartIcon } from 'glyphfox/react';

export function Motion({ open, copied, hasNews, liked }) {
  return (
    <>
      <MorphIcon name={copied ? 'check' : 'copy'} duration={300} />
      <MenuIcon morphTo={open ? 'x' : undefined} />
      <BellIcon animate="shake" trigger="state" active={hasNews} />
      <HeartIcon animate="pop" trigger="click" variant={liked ? 'solid' : 'outline'} />
    </>
  );
}

Für einen eigenen Renderer liefert useMorph(name, { duration }) die Icon-Daten des aktuellen Frames, die Sie über die Prop icon an Icon oder an Ihren eigenen Zeichencode übergeben können. Jede Animation berücksichtigt prefers-reduced-motion. Der Leitfaden zu animierten Icons geht Presets, Auslöser und die von Hand abgestimmten Morph-Paare durch.

import { Icon, useMorph } from 'glyphfox/react';

export function PlayButton({ playing }) {
  const frame = useMorph(playing ? 'pause' : 'play', { duration: 250 });
  return frame ? <Icon icon={frame.icon} variant={frame.variant} size={28} /> : null;
}

Refs, className, style und Events

Die Komponenten sind forwardRef-Komponenten, daher zeigt ein Ref auf das gerenderte <svg>-Element. className wird nach den eingebauten Klassen glyphfox glyphfox-NAME angehängt, style wird unverändert übergeben, und alle anderen SVG-Attribute und Event-Handler (onClick, data-*, aria-*, id) gehen direkt an das Element.

import { useRef } from 'react';
import { HeartIcon } from 'glyphfox/react';

export function Like({ onLike }) {
  const ref = useRef(null);
  const like = () => {
    ref.current?.animate([{ transform: 'scale(1)' }, { transform: 'scale(1.25)' }, { transform: 'scale(1)' }], 240);
    onLike();
  };
  return (
    <button type="button" onClick={like}>
      <HeartIcon ref={ref} className="like-icon" style={{ color: 'var(--accent)' }} />
      Like
    </button>
  );
}

Ein auf diese Weise übergebenes aria-label kennzeichnet das Icon außerdem als bedeutungstragend: Die Komponente wechselt automatisch von aria-hidden zu role="img".

TypeScript

Die Typen werden mit dem Paket ausgeliefert. GlyphIconComponent ist der Typ jeder Icon-Komponente, GlyphProps sind ihre Props (die gemeinsamen Props plus alle SVG-Attribute), und IconName aus dem Haupteinstiegspunkt ist der Union-Typ aller Icon-Namen, der Ihnen Autovervollständigung bei Icon und in Ihren eigenen Daten liefert.

import type { IconName } from 'glyphfox';
import { Icon, HomeIcon, SettingsIcon, type GlyphIconComponent } from 'glyphfox/react';

type NavItem = { label: string; href: string; icon: GlyphIconComponent };
const items: NavItem[] = [
  { label: 'Home', href: '/', icon: HomeIcon },
  { label: 'Settings', href: '/settings', icon: SettingsIcon },
];

export function Nav() {
  return (
    <nav>
      {items.map(({ label, href, icon: ItemIcon }) => (
        <a key={href} href={href}>
          <ItemIcon size={18} /> {label}
        </a>
      ))}
    </nav>
  );
}

export function Badge({ name }: { name: IconName }) {
  return <Icon name={name} variant="duotone" />;
}

Importe und Bundle-Größe

Benannte Importe aus glyphfox/react unterliegen dem Tree-Shaking: Jedes Icon ist ein eigenes Modul, das mit einer Pure-Annotation erzeugt wird, und das Paket deklariert, welche Dateien Seiteneffekte haben. Deep Imports wie glyphfox/react/icons/home laden direkt ein einzelnes Icon-Modul. Das hilft Tools ohne Tree-Shaking und verhindert, dass Entwicklungsserver den vollständigen Index anfassen.

import { HomeIcon } from 'glyphfox/react/icons/home';
import FileIcon from 'glyphfox/react/icons/file'; // default export works too

Was das Tree-Shaking aushebelt, was die gemeinsame Runtime kostet und warum die Build-Ausgabe einen winzigen Chunk pro Icon enthält, misst der Leitfaden zum Tree-Shaking nach.

Props

Alle Icon-Komponenten sowie Icon, Fusion und MorphIcon akzeptieren dieselben Props. Sie haben in Vue, Svelte, Angular, der Web Component und toSvg dieselben Namen und dieselbe Bedeutung, sodass ein aus dem Studio kopierter Wert überall funktioniert.

Icon und MorphIcon akzeptieren zusätzlich name (beliebige Namenssyntax) oder icon (Icon-Daten). Fusion akzeptiert icons, layout, gap, scale und offsets.

Stolperfallen

Icon bleibt anfangs leer

Ein noch nicht registrierter Name wird über einen dynamischen Import nachgeladen, daher ist das erste Rendering (und das Rendering auf dem Server) ein leeres SVG. Importieren Sie die Komponente, oder rufen Sie registerIcons mit den Daten aller Namen auf, die Sie per String rendern.

Server Components in Next.js

Die Komponenten verwenden Hooks, und das Paket hat keine "use client"-Direktive, daher kann eine Server Component sie nicht direkt rendern. Der Next.js-Leitfaden zeigt die Lösung mit einer einzigen Datei und eine Variante ganz ohne JavaScript.

Einfärben mit fill

Die Icons bestehen aus Strichen auf fill="none". Wenn Sie fill übergeben, wird jede Form gefüllt, was selten gewünscht ist. Verwenden Sie color (oder die CSS-Eigenschaft color an einem Elternelement) für den Strich und variant="solid" für gefüllte Formen.

Globales CSS überschreibt die Strichstärke

Eine Stylesheet-Regel wie svg { stroke-width: 1.5 } hat Vorrang vor dem SVG-Attribut, das die Achse der Strichstärke trägt, einschließlich ihrer optischen Kompensation. Schränken Sie den Geltungsbereich solcher Regeln ein, oder verwenden Sie die Prop weight.

Relative Größen umgehen die optische Kompensation

Die Kompensation muss die Pixelgröße kennen. Mit size="1em" bleibt der Strich bei der nominellen Strichstärke, was bei kleinen Schriftgrößen dünn wirken kann; übergeben Sie dort, wo es darauf ankommt, eine Pixelzahl oder einen etwas höheren weight-Wert.

createIcon beim Rendern aufrufen

createIcon(data) macht aus Ihren eigenen Icon-Daten eine Komponente mit allen Props. Rufen Sie die Funktion einmal auf Modulebene auf: Ein Aufruf innerhalb einer Komponente erzeugt bei jedem Rendering einen neuen Komponententyp und mountet das SVG neu.

import * mit dynamischem Schlüssel

Icons[name] auf einem Namespace-Import hält jedes Icon im Bundle. Verwenden Sie stattdessen Icon mit einem Namen; so wird nur geladen, was tatsächlich gerendert wird.