Iconos en HTML plano desde una CDN

Añade el script

El build de un solo archivo incluye todos los iconos, el elemento, el runtime de placeholders y el motor. Tanto jsDelivr como unpkg resuelven la URL del paquete sin ruta a ese archivo: 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>

Con defer, la descarga no bloquea el análisis del HTML. El script se ejecuta en cuanto se ha analizado el documento, define el elemento, inicializa todos los <glyph-fox> de la página y reemplaza los placeholders.

Fija la versión

glyphfox@1 sigue la última versión 1.x, algo cómodo mientras haces prototipos. En producción, fija la versión exacta y el archivo, para que la página no cambie nunca sin previo aviso y la CDN pueda guardar el archivo en caché indefinidamente.

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

Una versión exacta también admite integridad de subrecursos (Subresource Integrity): toma el hash de ese archivo, que jsDelivr muestra para cada archivo, y añade integrity y crossorigin="anonymous" a la etiqueta. Un rango como @1 no puede llevar hash, porque el archivo al que apunta cambia con cada versión.

También puedes alojarlo tú mismo. Copia node_modules/glyphfox/dist/web/glyphfox.min.js en tu carpeta pública y haz que la etiqueta apunte a él: el archivo es autocontenido y no hace más peticiones.

El elemento glyph-fox

Usa el elemento para los iconos que cambian: un nombre que cambia por otro, un morph, un disparador de hover o de clic, un estado. Lee todas las props de sus atributos y se vuelve a dibujar cuando cambia alguno de ellos.

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

El atributo morph anima el cambio de menu a x, uno de los pares ajustados a mano. Los estilos en el shadow DOM, los nombres de etiqueta personalizados y los disparadores se explican en la guía de web components.

Placeholders con data-glyph

Para los iconos que no cambian nunca, un placeholder es más ligero que un elemento activo. El runtime reemplaza por SVG en línea cada elemento que tenga un atributo data-glyph, copia su class al svg y sigue observando la página, así que también se reemplazan los placeholders que tus scripts añadan más tarde.

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

Las props son atributos de datos en kebab-case: data-size, data-weight, data-variant, data-modifier, data-animate y el resto de la tabla de abajo. Un aria-label en el placeholder se convierte en el título del icono, así que el svg recibe un nombre accesible.

El reemplazo ocurre una sola vez. Después, el placeholder desaparece, así que cambiar más tarde sus atributos de datos no tiene ningún efecto, y los listeners asociados al <i> se pierden con él. Asocia los listeners a un elemento padre, o usa el elemento cuando el icono tenga que cambiar.

Si usas un bundler, importa glyphfox/runtime en lugar del archivo de la CDN. Exporta replaceGlyphs y lo ejecuta al cargarse, e incluye todos los iconos, ya que una página puede pedir cualquier nombre. No cargues ese módulo directamente desde una CDN: importa el paquete como módulos ES separados, un archivo por icono, lo que supone cientos de peticiones. El build de un solo archivo ya contiene el mismo runtime.

La API global

El build para CDN también define window.glyphfox con la API del núcleo: toSvg, fuse, search, getIcon, iconNames, categories, createMorph, toDataUri, replaceGlyphs y más. Existe en cuanto se ha ejecutado el script, así que llámala desde un script de módulo colocado después de la etiqueta, o después de 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 convierte una cadena SVG en una URL para fondos CSS o para un <img>. Una imagen no puede heredar currentColor de la página, así que pasa un color explícito.

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 es el mismo build como módulo ES. Su exportación por defecto es el objeto de la API y, igual que el archivo clásico, define el elemento y ejecuta el runtime de placeholders.

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

Tamaño del archivo y cuándo es mejor compilar

El archivo único contiene todos los iconos: 216.4 KB minificado, 62.4 KB con gzip. Servido desde una CDN con caché de larga duración, es un precio razonable para un prototipo, un sitio de documentación o una página que muestra muchos iconos distintos. Para una landing page que muestra seis, no compensa.

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>

El build en CSS dibuja cada icono como una máscara rellena con currentColor, así que toma el color del texto y el tamaño de la fuente, e incluye las animaciones gf-spin y gf-pulse. Todos los comandos aceptan las props compartidas como opciones, por ejemplo --weight 1.5 o --variant duotone.

Atributos

El elemento y los placeholders leen las mismas props, en ambos casos en kebab-case: como atributos normales en <glyph-fox>, por ejemplo size y secondary-color, y con el prefijo data- en los placeholders, por ejemplo data-size y data-secondary-color. El elemento acepta además layout, gap y morph.

Errores comunes

Scripts que se ejecutan demasiado pronto

Un script clásico en línea se ejecuta durante el análisis del HTML, antes que un script diferido de la CDN, así que ahí window.glyphfox todavía no está definido. Usa type="module", ya que los scripts de módulo se ejecutan después de los scripts diferidos, en el orden del documento, o espera a DOMContentLoaded.

El módulo del runtime desde una CDN

dist/runtime/auto.js está pensado para bundlers. Si se carga directamente en el navegador, descarga el paquete módulo a módulo, un archivo por icono. En páginas de HTML plano, usa el build de un solo archivo.

Los placeholders se reemplazan una sola vez

Cambiar los atributos data-* después del reemplazo no tiene efecto, y los listeners del placeholder se descartan. Usa <glyph-fox> para los iconos que cambian.

Elementos autocerrados

<glyph-fox name="home" /> es solo una etiqueta de apertura en HTML, así que el contenido que va después desaparece dentro del elemento. Escribe siempre la etiqueta de cierre.

currentColor en imágenes

Un SVG usado como fuente de un <img> o como fondo CSS no puede ver el color de la página. Pasa un color a toSvg, o usa el subconjunto en CSS, que funciona con máscaras.

Disparadores de clic en placeholders

Los placeholders se convierten en SVG estático. Los morphs con hover y las animaciones se siguen reproduciendo, porque son CSS dentro del SVG, pero los disparadores de clic y de estado necesitan el elemento, que se encarga de cambiar los estados por ti.

Versiones flotantes en producción

glyphfox@1 cambia con cada versión 1.x, y un archivo modificado invalida el hash de integridad. Fija glyphfox@1.0.0 y la ruta completa del archivo.