Une bibliothèque d'icônes, une flèche, une étoile, un cœur, définie une seule fois puis appelée à dix endroits différents dans une interface, chacune avec sa propre taille : c'est exactement ce que permet <symbol>, un gabarit de dessin qui ne s'affiche jamais tout seul.
Sans lui, chaque icône répétée obligerait à copier-coller le même tracé complexe autant de fois qu'elle apparaît à l'écran, avec le poids de fichier et les risques d'erreur que cela suppose.
Définition
<symbol> définit une forme ou un groupe de formes réutilisable, identifié par un id, mais ne le rend jamais directement à l'écran. Un <symbol> placé dans un SVG n'affiche rien tant qu'aucun autre élément ne vient le référencer : c'est un gabarit en attente, pas un dessin.
Attributs principaux
| Attribut | Rôle |
|---|---|
id | Identifiant utilisé par <use> pour appeler ce symbole |
viewBox | Système de coordonnées interne, indépendant du document qui l'appelle |
preserveAspectRatio | Contrôle comment le symbole s'adapte si ses proportions changent |
Le viewBox d'un symbole est ce qui lui permet de s'adapter à n'importe quelle taille d'affichage sans déformation, exactement comme celui d'un <image> SVG classique.
Exemple de rendu concret
Un symbole d'étoile défini une seule fois, puis appelé trois fois à des tailles et des couleurs différentes.
<svg viewBox="0 0 300 100" xmlns="http://www.w3.org/2000/svg">
<symbol id="etoile" viewBox="0 0 24 24">
<path
d="M12 2 L15 9 L22 9 L16.5 13.5 L18.5 21 L12 16.5 L5.5 21 L7.5 13.5 L2 9 L9 9 Z"
fill="currentColor"
/>
</symbol>
<use href="#etoile" x="10" y="10" width="40" height="40" color="#f59e0b" />
<use href="#etoile" x="90" y="20" width="24" height="24" color="#f59e0b" />
<use href="#etoile" x="160" y="30" width="16" height="16" color="#f59e0b" />
</svg>Le <symbol> ne dessine rien tant qu'il n'est pas appelé : c'est <use> qui déclenche l'affichage, à chaque fois avec sa propre taille et sa propre couleur.
Différence avec le <template> HTML
<symbol> se comporte comme le <template> du HTML : les deux définissent un contenu qui reste totalement inerte tant que rien ne vient le cloner ou le référencer. Un <template> HTML doit être dupliqué en JavaScript avant d'apparaître dans la page ; un <symbol> SVG s'affiche simplement en le référençant avec <use>, sans copie de code ni ligne de script.
Piège classique : oublier que le contenu d'un <symbol> n'est jamais visible directement, même quand tout semble correctement écrit. Un débutant qui place un symbole dans son SVG puis se demande pourquoi rien n'apparaît a simplement oublié d'ajouter le <use> qui le déclenche.
Cas d'usage réel
Les bibliothèques d'icônes SVG, dans les menus, les boutons ou les badges, reposent presque toutes sur ce principe : un seul fichier regroupe des dizaines de symboles, chacun appelé à la demande par <use> dans l'interface, sans dupliquer le tracé de chaque icône. Ce découpage réduit aussi le poids du fichier final : au lieu de répéter un tracé de plusieurs centaines de points à chaque occurrence de l'icône, le document ne le stocke qu'une seule fois, et le navigateur réutilise la même définition en mémoire pour chaque copie affichée à l'écran.
Foire aux questions
Oui, un <symbol> se comporte comme un petit groupe : il peut rassembler plusieurs formes, des <path>, des cercles ou des blocs de texte, qui seront tous affichés ensemble à chaque appel du symbole.
use ?Non, un <symbol> reste invisible en toutes circonstances tant qu'aucun <use> ne le référence. C'est une différence essentielle avec un simple groupe, qui lui s'affiche directement dès qu'il est écrit dans le document.
Souvent tout au début du SVG, parfois dans un bloc caché en haut de la page HTML avec un style « display: none » posé sur le SVG englobant, pour que le navigateur les charge sans jamais les dessiner directement. Certains projets regroupent même tous leurs symboles dans un fichier externe unique, une véritable feuille de sprites, chargé une seule fois et mis en cache par le navigateur plutôt que retéléchargé sur chaque page du site.