Iconify est une couche entre votre application et les jeux d'icônes d'autres personnes. Au lieu d'installer un paquet distinct pour chaque jeu, vous donnez au composant un nom au format prefix:name et les données de l'icône arrivent soit d'une API publique, soit d'un fichier JSON local. La version 2.2.519 de @iconify/json, datée du 22 août 2026, contient 236 jeux et 334 616 icônes.
Ce qu'Iconify livre réellement
Le projet comporte trois couches faciles à confondre, car elles portent toutes le même nom.
La première est le format de données. Un jeu d'icônes est stocké comme un seul objet IconifyJSON avec les champs prefix, info, lastModified, icons, width et height. Le champ icons contient le contenu brut des éléments <svg> sans enveloppe, et les couleurs des icônes monochromes sont remplacées par currentColor. Changer la couleur d'une icône revient donc à changer la couleur du texte en CSS.
La deuxième est le jeu de données lui-même, le dépôt iconify/icon-sets publié sous forme de paquet @iconify/json. Il est actualisé plusieurs fois par semaine, ce que montre la numérotation : la 2.2.517 est sortie le 16 août 2026, la 2.2.518 le dix-huit et la 2.2.519 le vingt-deux.
La troisième est celle des composants et de l'outillage : @iconify/react, @iconify/vue, @iconify/svelte, le web component iconify-icon, le plugin de build unplugin-icons, les plugins Tailwind et la bibliothèque @iconify/utils pour manipuler les données.
Les couches sont indépendantes. Vous pouvez prendre le format seul et lire les données avec votre propre code, prendre les données seules et en générer des fichiers SVG, ou prendre un composant sans jamais toucher aux données. Cela explique pourquoi les paquets sont publiés séparément et pourquoi certains d'entre eux restent immobiles.
Quels paquets sont vivants et lesquels sont figés
C'est la première chose à vérifier, car la documentation et les tutoriels d'il y a quelques années pointent vers un paquet qu'il ne faut pas choisir aujourd'hui.
Le paquet @iconify/iconify est en version 3.1.1, publiée le 22 juin 2023, et rien n'est sorti depuis. Ce n'est pas un abandon mais un remplacement, et le registre npm le dit directement. Le champ deprecated des métadonnées de cette version contient une phrase qui indique que le paquet n'est plus maintenu et qu'il faut passer au web component moderne iconify-icon. Donc si vous trouvez dans une configuration de build une entrée qui dépose @iconify/iconify sur la page comme script, c'est un reste de l'approche de 2023.
Le reste de la famille est en bonne santé. Le tableau ci-dessous rassemble l'état au 22 août 2026, lu dans le registre npm.
| Paquet | Version | Date de sortie | Remarques |
|---|---|---|---|
@iconify/iconify | 3.1.1 | 2023-06-22 | marqué non maintenu, remplacé par iconify-icon |
iconify-icon | 3.0.2 | 2025-10-25 | web component, successeur du précédent |
@iconify/react | 6.0.2 | 2025-09-15 | dépendance pair react >=16 |
@iconify/vue | 5.0.1 | 2026-05-06 | dépendance pair vue >=3.0.0 |
@iconify/svelte | 5.2.2 | 2026-06-11 | dépendance pair svelte >5.0.0 |
@iconify/utils | 3.1.4 | 2026-07-05 | fonctions pour travailler avec les données |
@iconify/json | 2.2.519 | 2026-08-22 | données de tous les jeux |
@iconify/tools | 5.0.12 | 2026-05-21 | construire vos propres jeux |
unplugin-icons | 23.0.1 | 2026-01-14 | dépôt séparé, le projet unplugin |
@iconify/types | 2.0.0 | 2022-09-08 | types uniquement, stable depuis quatre ans |
Il vaut la peine de vérifier séparément les plages de dépendances au sein de la famille, car des désaccords s'y produisent. Ici, il n'y en a aucun. Chaque composant déclare @iconify/types dans la plage ^2.0.0 et la version actuelle de ce paquet est la 2.0.0. @iconify/tools 5.0.12 exige @iconify/utils dans la plage ^3.1.3 pour une version actuelle 3.1.4, et unplugin-icons 23.0.1 exige ^3.1.0. Les deux conditions sont remplies.
La date de 2022 sur @iconify/types ne signale pas de négligence. Ce paquet ne contient que des déclarations TypeScript pour le format de données, et le format n'a pas changé. Les plugins Tailwind sont une autre histoire : @iconify/tailwind 1.2.0 date du 7 décembre 2024 et cible la troisième version de Tailwind CSS, tandis que @iconify/tailwind4 1.2.3 du 5 mars 2026 cible la quatrième. Ce sont deux paquets différents, pas deux versions d'un même paquet.
La réponse à la question de ce qu'il faut choisir dans un nouveau projet en 2026 est donc : le composant pour votre framework ou iconify-icon, les données de @iconify/json ou de paquets à jeu unique, et unplugin-icons pour le build. N'installez pas @iconify/iconify.
Deux modes de composants : API et hors ligne
C'est la décision technique la plus importante avec cet outil, et le paquet React la montre le plus clairement, car il a deux points d'entrée distincts inscrits dans son champ exports.
L'import par défaut depuis @iconify/react est le mode API. Un composant qui reçoit un nom d'icône sous forme de chaîne consulte son cache et, si les données manquent, envoie une requête HTTP à https://api.iconify.design. Ce point d'entrée exporte les fonctions réseau : loadIcon, loadIcons, addAPIProvider, iconLoaded, setCustomIconLoader et l'objet _api.
Le second point d'entrée, @iconify/react/offline, n'exporte que quatre choses : Icon, InlineIcon, addCollection et addIcon. Il n'y a aucun code réseau dedans. Une icône que vous n'avez pas ajoutée au préalable par l'une de ces deux fonctions ne s'affichera tout simplement pas. Les signatures diffèrent aussi : en mode API, addCollection(data, provider?: string) renvoie un booléen, tandis qu'en mode hors ligne addCollection(data, prefix?: string | boolean) ne renvoie rien.
Voici le mode par défaut, celui qui charge les données depuis le serveur de quelqu'un d'autre.
// API mode: every newly displayed icon is an HTTP request
import { Icon } from '@iconify/react'
export function SaveButton() {
return (
<button type="button">
<Icon icon="mdi:content-save" width={20} height={20} />
Save
</button>
)
}Et voici le passage au hors ligne. Vous changez le chemin d'import et vous enregistrez vous-même les données.
// offline mode: no network traffic, data inside the application bundle
import { Icon, addCollection } from '@iconify/react/offline'
import iconsSubset from './icons/subset.json'
addCollection(iconsSubset)
export function SaveButton() {
return (
<button type="button">
<Icon icon="mdi:content-save" width={20} height={20} />
Save
</button>
)
}Vous devez produire vous-même subset.json, car intégrer tout le jeu mdi ajouterait 7 447 icônes au bundle. La fonction getIcons de @iconify/utils découpe un sous-ensemble, et lookupCollection de @iconify/json trouve le fichier source.
// scripts/build-icons.ts, run before the application build
import { writeFile } from 'node:fs/promises'
import { lookupCollection } from '@iconify/json'
import { getIcons } from '@iconify/utils'
const mdi = await lookupCollection('mdi')
const subset = getIcons(mdi, ['content-save', 'delete-outline', 'pencil'])
if (!subset) {
throw new Error('none of the requested icons were found')
}
await writeFile('./src/icons/subset.json', JSON.stringify(subset))La même paire de modes existe dans les autres composants. @iconify/vue 5.0.1 a une entrée ./offline dans son champ exports. @iconify/svelte 5.2.2 expose ./dist/OfflineIcon.svelte et ./dist/offline-functions à côté des variantes réseau.
Les arguments en faveur du mode API sont honnêtes : vous ne construisez rien, l'utilisateur ne télécharge que les icônes qu'il verra vraiment, et le composant intègre de la redondance. La documentation de l'API la décrit précisément : si l'hôte principal ne répond pas dans les 0,75 seconde, le composant essaie les adresses de secours https://api.simplesvg.com et https://api.unisvg.com, chacune pointant vers la moitié des serveurs.
Les arguments contre sont tout aussi concrets. Chaque affichage de page par un nouvel utilisateur signifie une requête vers un serveur que vous ne contrôlez pas, qui transporte son adresse IP et un en-tête Referer. Dans un projet soumis à un audit de confidentialité, c'est un point distinct à déclarer. La disponibilité des icônes dépend de l'infrastructure de quelqu'un d'autre, et la documentation indique clairement que les serveurs sont gratuits à utiliser mais pas gratuits à faire fonctionner, et demande un soutien financier. Il n'y a là aucun accord de niveau de service ni forfait payant avec garantie. S'y ajoute le scintillement au premier rendu, en partie atténué par les props ssr et fallback du composant pour React.
La troisième voie est de faire tourner votre propre API. Le code du serveur est ouvert, le paquet @iconify/api est en version 3.2.0 du 28 novembre 2025 sous MIT, et la documentation décrit un déploiement depuis le dépôt, depuis npm et depuis une image de conteneur. Vous pointez le composant vers votre propre adresse via addAPIProvider.
import { addAPIProvider, Icon } from '@iconify/react'
addAPIProvider('local', {
resources: ['https://icons.example.com']
})
// from now on a name with the provider prefix hits your own server
export const Save = () => <Icon icon="@local:mdi:content-save" />Les licences des jeux d'icônes, là où les audits trébuchent
Le code d'Iconify est uniformément ouvert. Le fichier license.txt du dépôt iconify/iconify contient le texte MIT avec une mention de copyright de Vjacheslav Trushkin couvrant 2021 à aujourd'hui, le champ license de npm pour @iconify/react, @iconify/vue, @iconify/svelte, @iconify/utils et @iconify/tools indique MIT, et l'archive publiée de @iconify/react 6.0.2 contient un fichier license.txt avec le texte MIT complet. Trois sources concordent, pas de surprise.
Les données, c'est une tout autre affaire, et c'est un vrai problème juridique plutôt qu'une formalité.
Le paquet @iconify/json 2.2.519 déclare MIT dans npm. Son contenu ne comporte cependant aucun fichier de licence à la racine. Le seul fichier contenant un texte de licence se trouve à lib/license.txt et couvre la classe utilitaire Finder pour PHP, avec une mention de copyright pour 2017 et 2018. Le dépôt iconify/icon-sets n'a pas non plus de fichier de licence à sa racine : les chemins license.txt, LICENSE et LICENSE.md renvoient tous une 404. Le champ MIT décrit donc du code utilitaire, pas les icônes.
Les icônes portent leurs propres licences, consignées dans le champ info.license de chaque fichier json/<prefix>.json. Le champ comporte trois sous-champs : title avec un nom lisible, spdx avec un identifiant et url avec une adresse du texte de la licence. Les mêmes données sont rassemblées dans collections.json et dans le fichier lisible collections.md du dépôt. La répartition des licences dans la version 2.2.519 se présente ainsi.
| Groupe de licences | Nombre de jeux | Ce que cela signifie en pratique |
|---|---|---|
| MIT | 106 | aucune restriction, mention de copyright obligatoire |
| CC BY 4.0 et CC BY 3.0 | 53 | attribution obligatoire dans le produit |
| Apache 2.0 | 31 | permissive, avec une clause de brevets |
| Open Font License | 13 | la vente des icônes seules comme fichier est interdite |
| CC BY-SA 4.0 et 3.0 | 9 | les œuvres dérivées sous la même licence |
| CC0 et Unlicense | 11 | domaine public |
| GPL 2.0 et GPL 3.0 | 6 | licence réciproque, un sujet pour votre juriste |
| ISC, MPL 2.0, BSD 3-Clause | 5 | permissives |
| CC BY-NC 4.0 et CC BY-NC-SA 4.0 | 2 | usage commercial interdit |
Le total est de 236, ce qui correspond au nombre de jeux dans collections.json.
Un exemple concret de jeu qui exige une attribution : fa6-brands, c'est-à-dire Font Awesome 6 Brands, 495 icônes, sous licence CC BY 4.0, auteur Dave Gandy. De même pour solar avec 7 608 icônes et selfhst avec 7 107 icônes. Si vous utilisez une seule icône de marque de fa6-brands dans votre interface, la licence vous oblige à nommer l'auteur et à identifier la licence.
Deux jeux sont interdits dans un produit commercial : cbi, nommé Custom Brand Icons, 1 718 icônes sous CC BY-NC-SA 4.0, et ps, nommé PrestaShop Icons, 479 icônes sous CC BY-NC 4.0. Six jeux relèvent de licences de la famille GPL, parmi lesquels dashicons avec 342 icônes et wordpress avec 341 icônes sous GPL-2.0-or-later, ainsi que icomoon-free avec 491 icônes sous GPL-3.0-or-later. Les icônes ne sont pas du code exécutable, donc la portée de la réciprocité se discute, mais c'est précisément le genre de discussion qu'on ne veut pas avoir dans un projet commercial.
Vérifier la licence d'un jeu donné avant de l'utiliser prend quelques lignes.
import { lookupCollections } from '@iconify/json'
const collections = await lookupCollections()
const risky = Object.entries(collections)
.filter(([, info]) => /NC|GPL|SA/.test(info.license.spdx ?? ''))
.map(([prefix, info]) => `${prefix}: ${info.license.spdx}`)
console.log(risky.join('\n'))La même lecture sans rien installer s'obtient avec une requête GET https://api.iconify.design/collections, qui renvoie un objet avec les mêmes champs license.title, license.spdx et license.url.
Les paquets à jeu unique se comportent autrement que le @iconify/json groupé, et en votre faveur. @iconify-json/mdi 1.2.3, daté du 20 janvier 2025, déclare Apache-2.0 dans npm, c'est-à-dire la licence du jeu lui-même plutôt que MIT. C'est une bonne nouvelle pour l'audit automatisé des dépendances. La mauvaise nouvelle est que l'archive ne contient aucun fichier de licence. Ses neuf fichiers sont index.js, index.mjs, index.d.ts, icons.json, info.json, metadata.json, chars.json, package.json et README.md. Vous devez joindre vous-même le texte d'Apache 2.0 à votre produit, en le récupérant à l'adresse du champ info.license.url.
Un dernier détail qui peut induire en erreur quand on recopie une liste de licences : le pied de page du site de documentation iconify.design mentionne une publication sous licence Apache 2.0 avec un copyright détenu par Iconify OÜ, alors que le fichier de licence du dépôt de code est MIT. Le pied de page couvre le contenu de la documentation ; le code de la bibliothèque est sous MIT.
La voie compilée : unplugin-icons et les plugins Tailwind
Une troisième approche saute entièrement le composant d'exécution. unplugin-icons transforme l'import d'un chemin virtuel en composant fini au moment du build, si bien que le navigateur reçoit du code SVG pur sans bibliothèque qui le cherche.
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import Icons from 'unplugin-icons/vite'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'
export default defineConfig({
plugins: [
react(),
Icons({
compiler: 'jsx',
jsx: 'react',
scale: 1.2,
defaultClass: 'icon',
autoInstall: false,
customCollections: {
brand: FileSystemIconLoader('./src/assets/icons')
}
})
]
})Dans le code de l'application, vous importez une icône par le chemin ~icons/mdi/content-save et le plugin le résout en composant. Le préfixe virtual:icons fonctionne toujours dans Vite, mais la documentation recommande ~icons pour la cohérence entre les outils de build. L'option autoInstall ajoute au projet les paquets de jeux manquants et est signalée comme expérimentale dans la documentation, donc sur un serveur de build il vaut mieux la laisser désactivée.
Le plugin est uniquement ESM, ce que sa documentation indique explicitement. Les dépendances pairs @svgr/core, @svgx/core, @vue/compiler-sfc et svelte sont marquées optionnelles dans le champ peerDependenciesMeta, donc votre gestionnaire de paquets n'exigera pas de paquets pour des frameworks que vous n'utilisez pas. Les exemples du dépôt couvrent Vite avec React et avec Vue 3, Next.js, Nuxt 4, SvelteKit et Astro.
Les plugins Tailwind sont à part ; ils génèrent des classes CSS qui rendent une icône comme image de fond ou comme masque, sans aucun élément dans l'arbre du document.
Il y a ici un chiffre que les sources rapportent différemment. Le registre npm indique un unpackedSize de 461 996 959 octets pour @iconify/json 2.2.519, et l'extraction de l'archive donne 442 MiB, dont 441 MiB pour le seul répertoire json. La documentation d'unplugin-icons, au même moment, parle d'environ 120 Mo. L'écart est de plus du double, donc quand vous planifiez l'espace de cache d'un serveur de build, budgétez d'après le chiffre du registre. Seules les icônes que vous utilisez atteignent le bundle de l'application, mais le téléchargement et l'extraction couvrent le tout.
Iconify face à Lucide et aux jeux uniques
Lucide, traité séparément, est un outil d'un autre genre, et comparer les deux de front vous égare.
| Critère | Iconify | Lucide | Paquet à jeu unique |
|---|---|---|---|
| Nombre d'icônes | 334 616 dans 236 jeux | 1 776 dans un seul jeu | dépend du jeu |
| Cohérence visuelle | aucune entre les jeux | un seul style, une seule grille | au sein du jeu |
| Licence des données | distincte pour chaque jeu | ISC avec une mention MIT séparée pour les icônes issues de Feather | une seule, déclarée dans npm |
| Source de données par défaut | API publique via le réseau | paquet npm, local | paquet npm, local |
| Empreinte d'installation | 442 MiB avec @iconify/json | un paquet par framework | de quelques à quelques dizaines de Mo |
| Quand y recourir | le choix des icônes n'est pas arrêté, logos nécessaires | un produit avec un seul style d'interface | un seul jeu cible connu |
Un choix sensé se présente ainsi. Si vous construisez un produit avec son propre langage visuel et que vous savez qu'un seul jeu cohérent suffira, prenez ce jeu directement. Lucide est présent dans Iconify sous le nom lucide avec 1 776 icônes sous ISC, donc vous ne perdez rien à passer par Iconify, mais vous ne gagnez rien non plus à part une couche supplémentaire. Il en va de même pour les logos de technologies, que vous trouverez nettoyés et accompagnés de leur licence dans svgl.
Iconify l'emporte dans trois situations. La première est un éditeur ou un configurateur où l'utilisateur choisit l'icône, car le moteur de recherche de l'API et l'accès à tous les jeux sont alors le cœur de la fonctionnalité. La deuxième est un panneau d'administration assemblé à partir de nombreuses sources, où vous avez de toute façon besoin d'icônes de plusieurs familles à la fois, par exemple des logos de marques à côté d'icônes d'interface. La troisième est un prototype où vous ne voulez pas encore vous engager sur un jeu.
Dans les projets construits sur Nuxt, il existe aussi le module nuxt-icon, et dans les bibliothèques de composants du genre shadcn/ui, les icônes arrivent déjà choisies avec les composants, donc ajouter Iconify à côté crée deux systèmes d'icônes parallèles dans une même application.
Erreurs courantes
Installer @iconify/iconify sur la foi d'un tutoriel plus ancien. Le paquet est figé depuis juin 2023 et porte une annotation npm sur son remplacement par iconify-icon. La version 3.1.1 s'installera encore et fonctionnera encore, mais elle ne recevra plus de corrections.
Laisser le mode API activé en production sans décision délibérée. Importer depuis @iconify/react sans le suffixe /offline signifie que chaque utilisateur interroge un serveur que vous ne contrôlez pas. C'est parfois acceptable, mais il faut que ce soit un choix et non un effet secondaire d'un exemple copié.
Supposer que, puisque @iconify/json est marqué MIT dans npm, toutes les icônes sont sous MIT. Le champ décrit du code utilitaire. Les icônes portent 19 licences différentes, dont deux interdisent l'usage commercial.
Intégrer un jeu entier dans le bundle de l'application via import icons from '@iconify-json/mdi/icons.json'. Ce fichier fait plus de trois mégaoctets et contient 7 447 icônes. Pour le mode hors ligne, préparez un sous-ensemble avec getIcons.
Confondre @iconify/tailwind avec @iconify/tailwind4. Ce ne sont pas des versions d'un même paquet mais deux paquets qui ciblent les troisième et quatrième versions de Tailwind, publiés indépendamment.
S'appuyer sur le moteur de recherche d'icônes sans vérifier le champ info.license du jeu choisi. Le catalogue affiche une licence à côté de chaque jeu, mais rien n'oblige à la lire, et copier un nom d'icône depuis les résultats de recherche est plus rapide que de lire des métadonnées.
FAQ
Quel paquet Iconify choisir pour un nouveau projet React ?
@iconify/react en version 6.0.2, ou le web component iconify-icon 3.0.2 avec l'enveloppe @iconify-icon/react 3.0.3. Le choix entre les deux revient à savoir si vous voulez un élément personnalisé dans l'arbre du document. N'installez pas @iconify/iconify, qui porte depuis juin 2023 une annotation npm de remplacement.
Les données d'icônes sont-elles chargées par le réseau par défaut ?
Oui. Importer depuis @iconify/react sans suffixe utilise l'API publique à https://api.iconify.design. Pour la désactiver, importez depuis @iconify/react/offline et enregistrez les données avec addCollection ou addIcon. Le point d'entrée hors ligne ne contient aucun code réseau.
Comment vérifier la licence d'un jeu précis ?
Lisez le champ info.license du fichier json/<prefix>.json dans le dépôt iconify/icon-sets, utilisez la fonction lookupCollections() du paquet @iconify/json, ou appelez GET https://api.iconify.design/collections. Les trois voies renvoient title, spdx et url.
Puis-je utiliser n'importe quelle icône Iconify dans un produit commercial ?
Non. Deux jeux sur 236 portent des licences qui interdisent l'usage commercial : cbi sous CC BY-NC-SA 4.0 et ps sous CC BY-NC 4.0. 53 autres exigent une attribution, et six relèvent de licences de la famille GPL.
Quel espace le jeu de données complet occupe-t-il ?
Le registre npm indique une taille décompressée de 461 996 959 octets pour @iconify/json 2.2.519, et la mesure du répertoire extrait donne 442 MiB. La documentation d'unplugin-icons annonce environ 120 Mo, ce qui ne correspond pas. Seules les icônes que vous utilisez atteignent le bundle de l'application.
L'API publique a-t-elle des limites de débit ou un forfait payant ?
La documentation n'indique ni limite ni tarif. Elle décrit les serveurs comme gratuits à utiliser, demande un soutien financier au projet et liste trois adresses pour la redondance. L'absence d'accord de niveau de service compte ici : si la disponibilité des icônes est critique, faites tourner votre propre API avec le paquet @iconify/api 3.2.0.