Preset de Iconos

Usa cualquier icono con CSS puro para UnoCSS.

TIP

Sigue las siguientes convenciones para usar los iconos

<prefix><collection>-<icon>
<prefix><collection>:<icon>

Por ejemplo:

html

<!-- Un icono de ancla básico de Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Una alarma naranja de Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Un logo de Vue grande -->
<div class="i-logos-vue text-3xl" />
<!-- Sol en modo claro, Luna en modo oscuro, de Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji de risa, se convierte en lágrimas al pasar el cursor -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Pasa el cursor

Consulta todos los iconos disponibles.

Instalación

pnpmyarnnpmbun

bash

pnpm add -D @unocss/preset-icons @iconify-json/[la-colección-que-quieres]

bash

yarn add -D @unocss/preset-icons @iconify-json/[la-colección-que-quieres]

bash

npm install -D @unocss/preset-icons @iconify-json/[la-colección-que-quieres]

bash

bun add -D @unocss/preset-icons @iconify-json/[la-colección-que-quieres]

Usamos Iconify como nuestra fuente de datos de iconos. Necesitas instalar el conjunto de iconos correspondiente en devDependencies siguiendo el patrón @iconify-json/*. Por ejemplo, @iconify-json/mdi para Material Design Icons, @iconify-json/tabler para Tabler. Puedes consultar Icônes o Iconify para todas las colecciones disponibles.

import presetIcons from '@unocss/preset-icons'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({ /* opciones */ }),
    // ...otros presets
  ],
})

TIP

Este preset está incluido en el paquete unocss, también puedes importarlo desde ahí:

import { presetIcons } from 'unocss'

INFO

¡También puedes usar este preset solo como complemento a tus frameworks de UI existentes para tener iconos CSS puros!

Si prefieres instalar todos los conjuntos de iconos disponibles en Iconify de una vez (~130MB):

pnpmyarnnpmbun

bash

pnpm add -D @iconify/json

bash

yarn add -D @iconify/json

bash

npm install -D @iconify/json

bash

bun add -D @iconify/json

Propiedades Extra

Puedes proporcionar las propiedades CSS extra para controlar el comportamiento predeterminado de los iconos. Lo siguiente es un ejemplo de hacer que los iconos sean inline por defecto:

presetIcons({
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
    // ...
  },
})

Sobrescribir Modos

Por defecto, este preset elegirá los modos de renderizado automáticamente para cada icono basándose en las características de los iconos. Puedes leer más en esta publicación del blog. En algunos casos, puedes querer establecer explícitamente los modos de renderizado para cada icono.

?bg para background-img - renderiza el icono como una imagen de fondo
?mask para mask - renderiza el icono como una imagen de máscara

Por ejemplo, vscode-icons:file-type-light-pnpm, un icono con colores (el svg no contiene currentColor) que será renderizado como una imagen de fondo. Usa vscode-icons:file-type-light-pnpm?mask para renderizarlo como una imagen de máscara y omitir sus colores.

html

<div class="w-full flex items-center justify-center gap-x-4 text-4xl p-2 mt-4">
  <div class="i-vscode-icons:file-type-light-pnpm" />
  <div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
</div>

Configurar colecciones y resolvers de iconos

Puedes proporcionar colecciones vía @iconify-json/[la-colección-que-quieres], @iconify/json o usando tus propias personalizadas usando la opción collections en tu configuración de UnoCSS.

Navegador

Para cargar colecciones de iconify deberías usar @iconify-json/[la-colección-que-quieres] y no @iconify/json ya que el archivo json es enorme.

Bundler

Cuando uses bundlers, puedes proporcionar las colecciones usando dynamic imports para que sean empaquetadas como chunk asíncrono y cargadas bajo demanda.

import presetIcons from '@unocss/preset-icons/browser'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        logos: () => import('@iconify-json/logos/icons.json').then(i => i.default),
      }
    })
  ]
})

CDN

O si prefieres obtenerlas desde CDN, puedes especificar la opción cdn desde v0.32.10. Recomendamos esm.sh como proveedor de CDN.

presetIcons({
  cdn: 'https://esm.sh/'
})

Personalización

También puedes proporcionar tus propias colecciones personalizadas usando CustomIconLoader o InlineCollection, por ejemplo usando InlineCollection:

presetIcons({
  collections: {
    custom: {
      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
      /* ... */
    },
    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default as any),
    /* ... */
  }
})

And then, you can use it on your html: <span class="i-custom:circle"></span>

Node.js

En Node.js el preset buscará automáticamente el dataset de iconify instalado, así que no necesitas registrar las colecciones de iconify.

También puedes proporcionar tus propias colecciones personalizadas usando también CustomIconLoader o InlineCollection.

FileSystemIconLoader

Adicionalmente, también puedes usar FileSystemIconLoader para cargar tus iconos personalizados desde tu sistema de archivos. Necesitarás instalar el paquete @iconify/utils como dependencia de desarrollo.

import fs from 'node:fs/promises'
// helpers del loader
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // clave como el nombre de la colección
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // carga tu icono personalizado de forma lazy
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // tu loader personalizado aquí. Haz lo que quieras.
          // por ejemplo, obtener desde un servidor remoto:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // un helper para cargar iconos desde el sistema de archivos
        // archivos bajo `./assets/icons` con extensión `.svg` serán cargados como su nombre de archivo
        // también puedes proporcionar un callback de transformación para cambiar cada icono (opcional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Desde @iconify/utils v2.1.20 puedes usar otros paquetes para cargar iconos de otros autores usando el nuevo helper createExternalPackageIconLoader.

ADVERTENCIA

Los paquetes externos deben incluir archivo icons.json con los datos de icons en formato IconifyJSON, que puede ser exportado con Iconify Tools. Consulta Exportar conjunto de iconos como paquete JSON para más detalles.

Por ejemplo, puedes usar an-awesome-collection o @my-awesome-collections/some-collection para cargar tus iconos personalizados o de terceros:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: createExternalPackageIconLoader('an-awesome-collection')
    })
  ]
})

También puedes combinarlo con otros loaders de iconos personalizados, por ejemplo:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        ...createExternalPackageIconLoader('other-awesome-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/^<svg /, '<svg fill="currentColor" ')
        )
      }
    })
  ]
})

Personalizaciones de Iconos

Puedes personalizar todos los iconos usando la opción de configuración customizations.

Funciones de personalización disponibles:

transform: transformar svg crudo, solo se aplicará cuando uses colección de iconos custom (colecciones iconify excluidas).
customize: cambiar valores de personalización predeterminados del icono.
iconCustomizer: cambiar valores de personalización predeterminados del icono.

Para cada icono cargado, las personalizaciones se aplicarán en este orden:

aplicar transform al svg crudo, si se proporciona y usas colección de iconos personalizada
aplicar customize con personalizaciones predeterminadas, si se proporciona
aplicar iconCustomizer con personalizaciones de customize, si se proporciona

Transformación Global de Iconos Personalizados

Cuando cargas tus iconos personalizados, puedes transformarlos, por ejemplo añadiendo atributo fill con currentColor:

presetIcons({
  customizations: {
    transform(svg) {
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Desde la versión 0.30.8 el transform proporciona los nombres de collection e icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // no aplicar fill a estos iconos en esta colección
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Personalización Global de Iconos

Cuando cargas cualquier icono puedes personalizar propiedades comunes a todos ellos, por ejemplo configurando el mismo tamaño:

presetIcons({
  customizations: {
    customize(props) {
      props.width = '2em'
      props.height = '2em'
      return props
    }
  }
})

Personalización de Icono/Colección

Puedes personalizar cada icono usando la opción de configuración iconCustomizer.

El iconCustomizer tendrá precedencia sobre la configuración.

El iconCustomizer se aplicará a cualquier colección, es decir, para cada icono del loader custom, inlined en custom collections o de @iconify.

Por ejemplo, puedes configurar iconCustomizer para cambiar todos los iconos de una colección o iconos individuales en una colección:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // personalizar todos los iconos en esta colección
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // personalizar este icono en esta colección
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // personalizar este icono @iconify en esta colección
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Directivas

Puedes usar la directiva icon() en tu CSS para obtener los metadatos del icono.

css

.icon {
  background-image: icon('i-carbon-sun');
}

WARNING

icon() depende de @unocss/preset-icons y usará la configuración, asegúrate de haber añadido este preset.

Más sobre la directiva icon(), consulta Directivas.

Opciones

scale

Tipo: number
Predeterminado: 1

Escala relacionada con el tamaño de fuente actual (1em).

mode

Tipo: 'mask' | 'bg' | 'auto'
Predeterminado: 'auto'
Ver: https://antfu.me/posts/icons-in-pure-css

Modo de iconos CSS generados.

TIP

mask - usar color de fondo y la propiedad mask para iconos monocromáticos
bg - usar imagen de fondo para los iconos, los colores son estáticos
auto - decidir inteligentemente el modo entre mask y bg por icono basándose en su estilo

prefix

Tipo: string | string[]
Predeterminado: 'i-'

Prefijo de clase para coincidir reglas de iconos.

extraProperties

Tipo: Record<string, string>
Predeterminado: {}

Propiedades CSS extra aplicadas al CSS generado.

warn

Tipo: boolean
Predeterminado: false

Emitir advertencia cuando se coinciden iconos faltantes.

iconifyCollectionsNames

Tipo: string[]
Predeterminado: undefined

Colecciones @iconify-json adicionales para usar. Esta opción debería usarse cuando hay nuevas colecciones @iconify-json no listadas en los nombres de colección predeterminados del preset de iconos.

collections

Tipo: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Predeterminado: undefined

En entorno Node.js, el preset buscará automáticamente el dataset de iconify instalado. Cuando uses en el navegador, esta opción se proporciona para proporcionar dataset con mecanismo de carga personalizado.

layer

Tipo: string
Predeterminado: 'icons'

Capa de regla.

customizations

Tipo: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Predeterminado: undefined

Personalizaciones de iconos personalizados.

autoInstall

Tipo: boolean
Predeterminado: false

Instalar automáticamente paquete de fuentes de iconos cuando se detecta el uso.

WARNING

Solo en entorno node, en browser esta opción será ignorada.

unit

Tipo: string
Predeterminado: 'em'

Unidad de icono personalizada.

cdn

Tipo: string
Predeterminado: undefined

Cargar iconos desde CDN. Debe comenzar con https:// y terminar con /.

Recomendados:

https://esm.sh/
https://cdn.skypack.dev/

customFetch

Tipo: (url: string) => Promise<any>
Predeterminado: undefined

El preset usa ofetch como fetcher predeterminado, también puedes personalizar la función fetch para proporcionar los datos del icono.

processor

Tipo: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Predeterminado: undefined

interface IconMeta {
  collection: string
  icon: string
  svg: string
  mode?: IconsOptions['mode']
}

Procesador para el objeto CSS antes de stringify. Consulta ejemplo.

Limpieza Avanzada de Conjunto de Iconos Personalizados

Cuando uses este preset con tus iconos personalizados, considera usar un proceso de limpieza similar al hecho por Iconify para cualquier conjunto de iconos. Todas las herramientas que necesitas están disponibles en Iconify Tools.

Puedes consultar este repo, usando este preset en un proyecto Vue 3: @iconify/tools/@iconify-demo/unocss.

Lee el artículo Limpiar iconos de Iconify para más detalles.

Preocupaciones de Accesibilidad

Cuando uses iconos, es importante tener en cuenta a todos tus usuarios potenciales. Algunos de ellos podrían estar usando lectores de pantalla, y necesitarán un texto alternativo para entender qué significa un icono. Puedes usar el atributo aria-label para proporcionar una descripción del icono:

html

<a href="/profile" aria-label="Perfil" class="i-ph:user-duotone"></a>

Si el icono es puramente decorativo y no necesita un texto alternativo, puedes usar aria-hidden="true" para ocultarlo de los lectores de pantalla:

html

<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  Mi Perfil
</a>

Hay muchas otras técnicas para proporcionar texto de pista para lectores de pantalla, por ejemplo, el preset Wind3 incluye sr-only para ocultar elementos visualmente pero mantenerlos accesibles para lectores de pantalla.

Puedes encontrar algunos buenos recursos en la web sobre accesibilidad de iconos, y los iconos CSS se comportan como fuentes de iconos, así que puedes usar las mismas técnicas que usarías con fuentes de iconos.

Créditos

Este preset está inspirado en este issue creado por @husayt.
Basado en el trabajo de este PR por @userquin.

Preset de Iconos ​

Instalación ​

Propiedades Extra ​

Sobrescribir Modos ​

Configurar colecciones y resolvers de iconos ​

Navegador ​

Bundler ​

CDN ​

Personalización ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Personalizaciones de Iconos ​

Transformación Global de Iconos Personalizados ​

Personalización Global de Iconos ​

Personalización de Icono/Colección ​

Directivas ​

Opciones ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Limpieza Avanzada de Conjunto de Iconos Personalizados ​

Preocupaciones de Accesibilidad ​

Créditos ​

Preset de Iconos

Instalación

Propiedades Extra

Sobrescribir Modos

Configurar colecciones y resolvers de iconos

Navegador

Bundler

CDN

Personalización

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Personalizaciones de Iconos

Transformación Global de Iconos Personalizados

Personalización Global de Iconos

Personalización de Icono/Colección

Directivas

Opciones

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Limpieza Avanzada de Conjunto de Iconos Personalizados

Preocupaciones de Accesibilidad

Créditos