Icons per CDN in reinem HTML

Das Skript einbinden

Der Einzeldatei-Build enthält alle Icons, das Element, die Platzhalter-Runtime und die Engine. jsDelivr und unpkg lösen die reine Paket-URL beide auf diese Datei auf: dist/web/glyphfox.min.js.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My page</title>
  <script defer src="https://cdn.jsdelivr.net/npm/glyphfox@1"></script>
  <!-- or https://unpkg.com/glyphfox@1 -->
</head>
<body>
  <glyph-fox name="home"></glyph-fox>
  <i data-glyph="search" data-size="20"></i>
</body>
</html>

Mit defer blockiert der Download das Parsen nicht. Das Skript läuft, sobald das Dokument geparst ist, definiert das Element, führt für jedes <glyph-fox> auf der Seite das Upgrade durch und ersetzt die Platzhalter.

Die Version festlegen

glyphfox@1 folgt dem jeweils neuesten 1.x-Release, was beim Prototyping praktisch ist. Legen Sie in Produktion die exakte Version und Datei fest, damit sich die Seite nie ohne Ihr Zutun ändert und das CDN die Datei dauerhaft cachen kann.

<script defer src="https://cdn.jsdelivr.net/npm/glyphfox@1.3.0/dist/web/glyphfox.min.js"></script>

Eine exakte Version lässt sich zusätzlich mit Subresource Integrity absichern: Nehmen Sie den Hash dieser Datei, den jsDelivr für jede Datei angibt, und ergänzen Sie das Tag um integrity und crossorigin="anonymous". Ein Versionsbereich wie @1 kann keinen Hash tragen, weil sich die Datei dahinter mit jedem Release ändert.

Sie können die Datei auch selbst hosten. Kopieren Sie node_modules/glyphfox/dist/web/glyphfox.min.js in Ihr öffentliches Verzeichnis und verweisen Sie im Tag darauf: Die Datei ist in sich abgeschlossen und stellt keine weiteren Anfragen.

Das glyph-fox-Element

Verwenden Sie das Element für Icons, die sich ändern: ein wechselnder Name, ein Morph, ein Hover- oder Klick-Auslöser, ein Zustand. Es liest alle Props aus seinen Attributen und zeichnet neu, sobald sich eines davon ändert.

<button type="button" class="menu" aria-label="Open menu" aria-expanded="false">
  <glyph-fox name="menu" morph duration="300"></glyph-fox>
</button>

<script type="module">
  const button = document.querySelector('.menu');
  const icon = button.querySelector('glyph-fox');
  button.addEventListener('click', () => {
    const open = button.getAttribute('aria-expanded') !== 'true';
    button.setAttribute('aria-expanded', String(open));
    button.setAttribute('aria-label', open ? 'Close menu' : 'Open menu');
    icon.setAttribute('name', open ? 'x' : 'menu');
  });
</script>

Das Attribut morph animiert den Wechsel von menu zu x (eines der von Hand abgestimmten Paare). Styling im Shadow-DOM, eigene Tag-Namen und Auslöser behandelt der Leitfaden zu Web Components.

Platzhalter mit data-glyph

Für Icons, die sich nie ändern, ist ein Platzhalter schlanker als ein aktives Element. Die Runtime ersetzt jedes Element mit einem data-glyph-Attribut durch Inline-SVG, überträgt seine class auf das svg und beobachtet die Seite weiter, sodass auch Platzhalter ersetzt werden, die Ihre Skripte später hinzufügen.

<i data-glyph="search" data-size="20"></i>
<i data-glyph="file+check@tr" data-weight="1.5"></i>
<i data-glyph="folder" data-variant="duotone" data-secondary-color="#ff7a1a"></i>
<i data-glyph="trash" class="danger" aria-label="Delete"></i>

Props sind Data-Attribute in Kebab-Case: data-size, data-weight, data-variant, data-modifier, data-animate und alle weiteren aus der Tabelle unten. Ein aria-label am Platzhalter wird zum Titel des Icons, sodass das svg einen zugänglichen Namen erhält.

Die Ersetzung geschieht nur einmal. Danach ist der Platzhalter verschwunden: Spätere Änderungen an seinen Data-Attributen bewirken nichts, und am <i> registrierte Listener gehen mit ihm verloren. Hängen Sie Listener an ein Elternelement, oder verwenden Sie das Element, wenn sich das Icon ändern muss.

Mit einem Bundler importieren Sie statt der CDN-Datei glyphfox/runtime. Das Modul exportiert replaceGlyphs, führt es beim Laden aus und enthält alle Icons, da eine Seite jeden beliebigen Namen anfordern kann. Laden Sie dieses Modul nicht direkt von einem CDN: Es importiert das Paket als einzelne ES-Module, eine Datei pro Icon, was Hunderte von Anfragen kostet. Der Einzeldatei-Build enthält bereits dieselbe Runtime.

Die globale API

Der CDN-Build setzt außerdem window.glyphfox mit der Core-API: toSvg, fuse, search, getIcon, iconNames, categories, createMorph, toDataUri, replaceGlyphs und weitere. Das Objekt existiert, sobald das Skript gelaufen ist; rufen Sie die API daher aus einem Modul-Skript auf, das nach dem Tag steht, oder erst nach DOMContentLoaded.

<input type="search" id="q" placeholder="Search icons" aria-label="Search icons">
<div id="results"></div>

<script type="module">
  const { search, toSvg } = window.glyphfox;
  const q = document.getElementById('q');
  const results = document.getElementById('results');
  q.addEventListener('input', () => {
    results.innerHTML = search(q.value, { limit: 24 })
      .map((icon) => `<button type="button" aria-label="${icon.name}">${toSvg(icon.name, { size: 28 })}</button>`)
      .join('');
  });
</script>

toDataUri wandelt einen SVG-String in eine URL für CSS-Hintergründe oder ein <img> um. Ein Bild kann currentColor nicht von der Seite erben, geben Sie daher eine explizite Farbe an.

const { toDataUri, toSvg } = window.glyphfox;
const check = toDataUri(toSvg('check', { size: 16, color: '#16a34a' }));
document.documentElement.style.setProperty('--icon-check', `url("${check}")`);

.done::before {
  content: '';
  display: inline-block;
  width: 16px;
  height: 16px;
  margin-right: 6px;
  background: var(--icon-check) no-repeat center / contain;
}

dist/web/glyphfox.esm.js ist derselbe Build als ES-Modul. Sein Default-Export ist das API-Objekt, und wie die klassische Datei definiert er das Element und führt die Platzhalter-Runtime aus.

<div id="logo"></div>

<script type="module">
  import glyphfox from 'https://cdn.jsdelivr.net/npm/glyphfox@1/dist/web/glyphfox.esm.js';

  document.getElementById('logo').innerHTML = glyphfox.toSvg('fox', { size: 48, variant: 'duotone' });
</script>

Dateigröße und wann sich ein eigener Build lohnt

Die Einzeldatei enthält alle Icons: 216,4 KB minifiziert, 62,4 KB mit gzip. Von einem CDN mit langem Caching ausgeliefert, ist das ein fairer Preis für einen Prototyp, eine Dokumentationsseite oder eine Seite mit vielen verschiedenen Icons. Für eine Landingpage, die sechs Icons zeigt, ist es ein schlechter Tausch.

npx glyphfox build home search menu loader --type css --out public
npx glyphfox build home search menu loader --type sprite --out public/icons

<link rel="stylesheet" href="/glyphfox.css">

<span class="gf gf-home" aria-hidden="true"></span>
<span class="gf gf-loader gf-spin" aria-hidden="true"></span>

Der CSS-Build zeichnet jedes Icon als Maske, die mit currentColor gefüllt ist; so übernimmt das Icon Textfarbe und Schriftgröße. Außerdem enthält der Build die Animationen gf-spin und gf-pulse. Jeder Befehl nimmt die gemeinsamen Props als Flags entgegen, etwa --weight 1.5 oder --variant duotone.

Attribute

Das Element und die Platzhalter lesen dieselben Props, jeweils in Kebab-Case: als einfache Attribute an <glyph-fox>, etwa size und secondary-color, und mit dem Präfix data- an Platzhaltern, etwa data-size und data-secondary-color. Das Element akzeptiert zusätzlich layout, gap und morph.

Stolperfallen

Skripte, die zu früh laufen

Ein klassisches Inline-Skript läuft während des Parsens und damit vor einem CDN-Skript mit defer, dort ist window.glyphfox also noch undefiniert. Verwenden Sie type="module", da Modul-Skripte in Dokumentreihenfolge nach Skripten mit defer ausgeführt werden, oder warten Sie auf DOMContentLoaded.

Das Runtime-Modul von einem CDN

dist/runtime/auto.js ist für Bundler gedacht. Direkt im Browser geladen, holt es das Paket Modul für Modul, eine Datei pro Icon. Verwenden Sie auf einfachen Seiten den Einzeldatei-Build.

Platzhalter werden nur einmal ersetzt

Änderungen an data-*-Attributen nach der Ersetzung haben keine Wirkung, und Listener am Platzhalter gehen verloren. Verwenden Sie <glyph-fox> für Icons, die sich ändern.

Selbstschließende Elemente

<glyph-fox name="home" /> ist in HTML nur ein öffnendes Tag, der nachfolgende Inhalt verschwindet also im Element. Schreiben Sie immer das schließende Tag.

currentColor in Bildern

SVG, das als Quelle eines <img> oder als CSS-Hintergrund dient, sieht die Farbe der Seite nicht. Übergeben Sie toSvg eine Farbe, oder verwenden Sie das CSS-Subset, das mit Masken arbeitet.

Klick-Auslöser an Platzhaltern

Platzhalter werden zu statischem SVG. Hover-Morphs und Animationen laufen weiterhin, weil sie als CSS im SVG stecken, Klick- und Zustands-Auslöser brauchen jedoch das Element, das die Zustände für Sie umschaltet.

Nicht fixierte Versionen in Produktion

glyphfox@1 wandert mit jedem 1.x-Release mit, und eine geänderte Datei macht einen Integrity-Hash ungültig. Legen Sie glyphfox@1.0.0 und den vollständigen Dateipfad fest.