Preset Icons

Utilisez n'importe quelle icône avec du CSS pur pour UnoCSS.

TIP

Suivez les conventions suivantes pour utiliser les icônes

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

Par exemple :

html

<!-- Une icône d'ancre basique de Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Une alarme orange de Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Un grand logo Vue -->
<div class="i-logos-vue text-3xl" />
<!-- Soleil en mode clair, Lune en mode sombre, de Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji de rire, se transforme en larme au survol -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Survolez-le

Consultez toutes les icônes disponibles.

Installation

pnpmyarnnpmbun

bash

pnpm add -D @unocss/preset-icons @iconify-json/[la-collection-que-vous-voulez]

bash

yarn add -D @unocss/preset-icons @iconify-json/[la-collection-que-vous-voulez]

bash

npm install -D @unocss/preset-icons @iconify-json/[la-collection-que-vous-voulez]

bash

bun add -D @unocss/preset-icons @iconify-json/[la-collection-que-vous-voulez]

Nous utilisons Iconify comme source de données d'icônes. Vous devez installer l'ensemble d'icônes correspondant dans devDependencies en suivant le modèle @iconify-json/*. Par exemple, @iconify-json/mdi pour Material Design Icons, @iconify-json/tabler pour Tabler. Vous pouvez vous référer à Icônes ou Iconify pour toutes les collections disponibles.

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

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

TIP

Ce preset est inclus dans le package unocss, vous pouvez aussi l'importer depuis là :

import { presetIcons } from 'unocss'

INFO

Vous pouvez aussi utiliser ce preset seul comme complément à vos frameworks UI existants pour avoir des icônes CSS pur !

Si vous préférez installer tous les ensembles d'icônes disponibles sur Iconify d'un coup (~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

Propriétés supplémentaires

Vous pouvez fournir les propriétés CSS supplémentaires pour contrôler le comportement par défaut des icônes. Voici un exemple pour rendre les icônes inline par défaut :

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

Remplacement des modes

Par défaut, ce preset choisira automatiquement les modes de rendu pour chaque icône basé sur les caractéristiques des icônes. Vous pouvez en lire plus dans cet article de blog. Dans certains cas, vous pouvez vouloir définir explicitement les modes de rendu pour chaque icône.

?bg pour background-img - rend l'icône comme une image de fond
?mask pour mask - rend l'icône comme une image de masque

Par exemple, vscode-icons:file-type-light-pnpm, une icône avec des couleurs (le svg ne contient pas currentColor) qui sera rendue comme une image de fond. Utilisez vscode-icons:file-type-light-pnpm?mask pour la rendre comme une image de masque et contourner ses couleurs.

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>

Configuration des collections et résolveurs d'icônes

Vous pouvez fournir des collections via @iconify-json/[la-collection-que-vous-voulez], @iconify/json ou en utilisant vos propres collections personnalisées avec l'option collections dans votre configuration UnoCSS.

Navigateur

Pour charger les collections iconify, vous devriez utiliser @iconify-json/[la-collection-que-vous-voulez] et non @iconify/json puisque le fichier json est énorme.

Bundler

Quand vous utilisez des bundlers, vous pouvez fournir les collections en utilisant des imports dynamiques pour qu'elles soient bundlées comme chunk asynchrone et chargées à la demande.

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

Ou si vous préférez les récupérer depuis un CDN, vous pouvez spécifier l'option cdn depuis v0.32.10. Nous recommandons esm.sh comme fournisseur CDN.

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

Personnalisation

Vous pouvez aussi fournir vos propres collections personnalisées en utilisant CustomIconLoader ou InlineCollection, par exemple en utilisant 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),
    /* ... */
  }
})

Et ensuite, vous pouvez l'utiliser dans votre html : <span class="i-custom:circle"></span>

Node.js

Dans Node.js, le preset cherchera automatiquement l'ensemble de données iconify installé, donc vous n'avez pas besoin d'enregistrer les collections iconify.

Vous pouvez aussi fournir vos propres collections personnalisées en utilisant aussi CustomIconLoader ou InlineCollection.

FileSystemIconLoader

De plus, vous pouvez aussi utiliser FileSystemIconLoader pour charger vos icônes personnalisées depuis votre système de fichiers. Vous devrez installer le package @iconify/utils comme dépendance de développement.

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

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // clé comme nom de collection
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // chargez votre icône personnalisée paresseusement
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // votre loader personnalisé ici. Faites ce que vous voulez.
          // par exemple, récupérez depuis un serveur distant :
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // un helper pour charger les icônes depuis le système de fichiers
        // les fichiers sous `./assets/icons` avec l'extension `.svg` seront chargés comme leur nom de fichier
        // vous pouvez aussi fournir une fonction de transformation pour changer chaque icône (optionnel)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

De @iconify/utils v2.1.20 vous pouvez utiliser d'autres packages pour charger les icônes de d'autres auteurs en utilisant la nouvelle createExternalPackageIconLoader helper.

WARNING

Les packages externes doivent inclure le fichier icons.json avec les données IconifyJSON, qui peut être exporté avec Iconify Tools. Vérifiez Exporting icon set as JSON package pour plus de détails.

Par exemple, vous pouvez utiliser an-awesome-collection ou @my-awesome-collections/some-collection pour charger vos icônes personnalisées ou tierces :

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

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

Vous pouvez aussi les combiner avec d'autres chargeurs d'icônes personnalisées, par exemple :

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" ')
        )
      }
    })
  ]
})

Personnalisation des icônes

Vous pouvez personnaliser toutes les icônes en utilisant l'option customizations de configuration.

Les fonctions de personnalisation disponibles :

transform: transformer le svg brut, ne sera appliqué que lors de l'utilisation d'une icône personnalisée (iconify collections exclues).
customize: changer les valeurs par défaut de personnalisation des icônes.
iconCustomizer: changer les valeurs par défaut de personnalisation des icônes.

Pour chaque icône chargée, les personnalisations seront appliquées dans cet ordre :

appliquer transform au svg brut, si fourni et utilisé pour une icône personnalisée
appliquer customize avec les personnalisations par défaut, si fourni
appliquer iconCustomizer avec les personnalisations customize, si fourni

Global Custom Icon Transformation

Lors de la chargement de vos icônes personnalisées, vous pouvez les transformer, par exemple en ajoutant l'attribut fill avec currentColor :

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

De la version 0.30.8 le transform fournit les noms de collection et icon :

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // ne pas appliquer le remplissage à ces icônes sur cette collection
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Global Icon Customization

Lors de la chargement de toute icône, vous pouvez personnaliser les propriétés communes à toutes :

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

Icon/Collection Customization

Vous pouvez personnaliser chaque icône en utilisant l'option iconCustomizer de configuration.

Le iconCustomizer prendra la priorité sur la configuration.

Le iconCustomizer sera appliqué à toute collection, c'est-à-dire, pour chaque icône de custom loader, inlined sur collections custom ou de @iconify.

Par exemple, vous pouvez configurer iconCustomizer pour changer toutes les icônes d'une collection ou des icônes individuelles d'une collection :

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // personnaliser toutes les icônes dans cette collection
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // personnaliser cette icône dans cette collection
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // personnaliser cette icône @iconify dans cette collection
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Directives

Vous pouvez utiliser la directive icon() dans votre CSS pour obtenir les métadonnées de l'icône.

css

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

WARNING

icon() dépend de @unocss/preset-icons et utilisera la configuration, assurez-vous d'avoir ajouté ce preset.

Plus d'informations sur la directive icon(), vérifiez Directives.

Options

scale

Type: number
Défaut: 1

Échelle relative à la taille de police actuelle (1em).

mode

Type: 'mask' | 'bg' | 'auto'
Défaut: 'auto'
Voir: https://antfu.me/posts/icons-in-pure-css

Mode des icônes CSS générées.

TIP

mask - utiliser la couleur de fond et la propriété mask pour les icônes monochromes
bg - utiliser l'image de fond pour les icônes, les couleurs sont statiques
auto - décider intelligemment le mode entre mask et bg par icône basé sur son style

prefix

Type: string | string[]
Défaut: 'i-'

Préfixe de classe pour matcher les règles d'icônes.

extraProperties

Type: Record<string, string>
Défaut: {}

Propriétés CSS supplémentaires appliquées au CSS généré.

warn

Type: boolean
Défaut: false

Émettre un avertissement quand des icônes manquantes sont matchées.

iconifyCollectionsNames

Type: string[]
Défaut: undefined

Collections @iconify-json supplémentaires à utiliser. Cette option devrait être utilisée quand il y a de nouvelles collections @iconify-json non listées dans les noms de collections par défaut du preset d'icônes.

collections

Type: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Défaut: undefined

Dans l'environnement Node.js, le preset cherchera automatiquement l'ensemble de données iconify installé. Quand utilisé dans le navigateur, cette option est fournie pour fournir l'ensemble de données avec un mécanisme de chargement personnalisé.

layer

Type: string
Défaut: 'icons'

Couche de règle.

customizations

Type: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Défaut: undefined

Personnalisations d'icônes personnalisées.

autoInstall

Type: boolean
Défaut: false

Installer automatiquement le package de sources d'icônes quand l'utilisation est détectée.

WARNING

Seulement dans l'environnement node, dans le navigateur cette option sera ignorée.

unit

Type: string
Défaut: 'em'

Unité d'icône personnalisée.

cdn

Type: string
Défaut: undefined

Charger les icônes depuis un CDN. Doit commencer par https:// et se terminer par /.

Recommandations :

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

customFetch

Type: (url: string) => Promise<any>
Défaut: undefined

Le preset utilise ofetch comme fetch par défaut, vous pouvez aussi personnaliser la fonction fetch pour fournir les données d'icônes.

processor

Type: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Défaut: undefined

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

Processeur pour l'objet CSS avant la stringification. Voir exemple.

Nettoyage avancé d'ensemble d'icônes personnalisées

Quand vous utilisez ce preset avec vos icônes personnalisées, considérez utiliser un processus de nettoyage similaire à celui fait par Iconify pour tout ensemble d'icônes. Tous les outils dont vous avez besoin sont disponibles dans Iconify Tools.

Vous pouvez vérifier ce repo, utilisant ce preset sur un projet Vue 3 : @iconify/tools/@iconify-demo/unocss.

Lisez l'article Cleaning up icons de Iconify pour plus de détails.

Préoccupations d'accessibilité

Quand vous utilisez des icônes, il est important de prendre en compte tous vos utilisateurs potentiels. Certains d'entre eux pourraient utiliser des lecteurs d'écran, et ils auront besoin d'un texte alternatif pour comprendre ce qu'une icône signifie. Vous pouvez utiliser l'attribut aria-label pour fournir une description de l'icône :

html

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

Si l'icône est purement décorative et n'a pas besoin d'un texte alternatif, vous pouvez utiliser aria-hidden="true" pour la cacher des lecteurs d'écran :

html

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

Il y a beaucoup d'autres techniques pour fournir du texte d'indice pour les lecteurs d'écran, par exemple, le preset Wind3 inclut sr-only pour cacher les éléments visuellement mais les garder accessibles aux lecteurs d'écran.

Vous pouvez trouver de bonnes ressources sur le web sur l'accessibilité des icônes, et les icônes CSS se comportent comme les polices d'icônes, donc vous pouvez utiliser les mêmes techniques que vous utiliseriez avec les polices d'icônes.

Crédits

Ce preset est inspiré de cette issue créée par @husayt.
Basé sur le travail de cette PR par @userquin.

Preset Icons ​

Installation ​

Propriétés supplémentaires ​

Remplacement des modes ​

Configuration des collections et résolveurs d'icônes ​

Navigateur ​

Bundler ​

CDN ​

Personnalisation ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Personnalisation des icônes ​

Global Custom Icon Transformation ​

Global Icon Customization ​

Icon/Collection Customization ​

Directives ​

Options ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Nettoyage avancé d'ensemble d'icônes personnalisées ​

Préoccupations d'accessibilité ​

Crédits ​

Preset Icons

Installation

Propriétés supplémentaires

Remplacement des modes

Configuration des collections et résolveurs d'icônes

Navigateur

Bundler

CDN

Personnalisation

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Personnalisation des icônes

Global Custom Icon Transformation

Global Icon Customization

Icon/Collection Customization

Directives

Options

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Nettoyage avancé d'ensemble d'icônes personnalisées

Préoccupations d'accessibilité

Crédits