Déclarer des icônes SVG personnalisées dans WordPress 7.1
Ajouter une icône SVG personnalisée à l’éditeur de blocs a longtemps imposé JavaScript, une étape de build ou une solution de contournement incomplète. WordPress 7.1 doit introduire une API publique qui permet de déclarer des icônes depuis une extension PHP, puis de les employer dans l’éditeur, les modèles PHP et l’API REST.
Ce guide crée une extension myplugin-custom-icons qui déclare une collection, ajoute une icône en ligne et deux icônes depuis des fichiers, automatise l’enregistrement d’un dossier entier et expose un shortcode. WordPress 7.1 est annoncé pour le 19 août 2026 ; le code ci-dessous correspond à l’API attendue dans cette version.
Ce que l’extension va fournir
- Une extension
myplugin-custom-iconset une collection d’icônes nomméemyplugin. - Trois icônes prêtes à l’emploi : un cœur déclaré en ligne, une étoile et un marque-page chargés depuis des fichiers
.svg. - Un mécanisme d’enregistrement groupé qui détecte et ajoute automatiquement tous les SVG d’un dossier.
- Un shortcode utilisable dans le contenu des publications pour insérer n’importe quelle icône déclarée.
- Une icône personnalisée employée comme icône d’un bloc, y compris pour un bloc déclaré uniquement en PHP.
Prérequis
- WordPress 7.1 ou une version ultérieure ; la release candidate 7.1 convient au développement.
- Quelques fichiers d’icônes SVG, y compris ceux fournis plus loin.
- Un environnement local, par exemple LocalWP, WordPress Studio ou
wp-env. - Les bases de PHP.
Comprendre l’API des icônes
L’API repose sur trois fonctions et sur les collections. Une collection est un groupe nommé d’icônes : chaque icône doit y appartenir, et son nom préfixe les identifiants pour éviter les conflits avec le core ou avec une autre extension. Ainsi, core/plus et myplugin/plus restent deux icônes distinctes.
wp_register_icon_collection( $name, $args )déclare une collection nommée.wp_register_icon( $name, $args )déclare une icône.wp_get_icon( $name, $args )génère le SVG dans PHP et renvoie une chaîne de caractères.
Lors de l’enregistrement, fournissez soit content, qui contient le balisage SVG dans une chaîne PHP, soit file_path, qui contient le chemin absolu d’un fichier .svg. N’employez pas les deux pour une même icône. content convient à une ou deux icônes ; file_path s’adapte mieux à une bibliothèque stockée dans un dossier.
1. Créer l’extension et déclarer sa collection
Déclarez toujours la collection avant ses icônes. Si vous tentez d’ajouter une icône à une collection absente, elle n’apparaît pas dans le sélecteur sans signaler d’erreur.
Créez l’arborescence suivante dans wp-content/plugins/ :
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgAjoutez ensuite l’en-tête de l’extension et l’enregistrement de la collection dans myplugin-custom-icons.php :
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Declare custom SVG icons for WordPress 7.1+.
* Version: 1.0.0
* Requires at least: 7.1
* Requires PHP: 7.4
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'MYPLUGIN_ICONS_PATH', plugin_dir_path( __FILE__ ) );
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Le nom myplugin devient le préfixe de chaque icône : myplugin/heart, myplugin/star ou myplugin/bookmark. Le label sert de titre de section dans le sélecteur. Activez l’extension depuis Extensions → Extensions installées : une collection vide ne produit encore aucun rendu.
2. Déclarer les icônes avec les deux méthodes
Déclarer un SVG en ligne avec content
Placez le SVG du cœur directement dans le fichier PHP quand vous ne gérez qu’un petit nombre d’icônes. Accrochez cette fonction à init avec la priorité 20 : elle s’exécutera après l’enregistrement de la collection, qui utilise la priorité par défaut 10.
add_action( 'init', 'myplugin_register_inline_icons', 20 );
function myplugin_register_inline_icons() {
wp_register_icon(
'myplugin/heart',
array(
'label' => __( 'Heart', 'myplugin-icons' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>',
)
);
}Le nom respecte le format collection/icon-slug. Le label s’affiche dans le sélecteur, tandis que content porte le SVG. Grâce à stroke="currentColor", l’icône hérite de la couleur du texte environnant au lieu d’imposer une couleur de contour.
Déclarer des fichiers SVG avec file_path
Enregistrez l’étoile et le marque-page depuis le disque avec file_path. Créez d’abord les deux fichiers suivants dans le dossier icons/.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
</svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/>
</svg>Référencez-les ensuite dans l’extension. WordPress lit le fichier lorsqu’il en a besoin.
add_action( 'init', 'myplugin_register_file_icons', 20 );
function myplugin_register_file_icons() {
wp_register_icon(
'myplugin/star',
array(
'label' => __( 'Star', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/star.svg',
)
);
wp_register_icon(
'myplugin/bookmark',
array(
'label' => __( 'Bookmark', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/bookmark.svg',
)
);
}Ouvrez le bloc core/icon dans l’éditeur. Le sélecteur ajoute une section MyPlugin avec Heart, Star et Bookmark, que vous pouvez insérer directement. Si une icône manque, vérifiez d’abord l’ordre des hooks : la collection doit s’enregistrer à la priorité par défaut et les icônes après, par exemple à la priorité 20.
core/icon. — Forrás: WPVibes3. Déclarer automatiquement un dossier d’icônes
Une bibliothèque réelle ne se gère pas avec trente appels manuels à wp_register_icon(). Remplacez la fonction myplugin_register_file_icons() par la version suivante : elle détecte tous les fichiers SVG du dossier et les déclare à chaque requête.
add_action( 'init', 'myplugin_register_all_file_icons', 20 );
function myplugin_register_all_file_icons() {
$icons_dir = MYPLUGIN_ICONS_PATH . 'icons/';
$svg_files = glob( $icons_dir . '*.svg' );
if ( empty( $svg_files ) ) {
return;
}
foreach ( $svg_files as $file_path ) {
$slug = basename( $file_path, '.svg' );
$label = ucwords( str_replace( '-', ' ', $slug ) );
wp_register_icon(
'myplugin/' . $slug,
array(
'label' => $label,
'file_path' => $file_path,
)
);
}
}glob( $icons_dir . '*.svg' )renvoie chaque fichier.svgprésent dans le dossier.basename( $file_path, '.svg' )extrait le nom sans son extension :advanced-button.svgdevientadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )transforme ce slug en libellé lisible :advanced-buttondevient « Advanced Button ».- La boucle ajoute chaque icône à la collection
myplugin/.
Déposez un nouveau SVG dans icons/, actualisez l’éditeur et l’icône apparaîtra sans modifier le PHP. Ce schéma conserve le cœur déclaré en ligne et couvre l’étoile, le marque-page ainsi que toutes les icônes supplémentaires du dossier.
4. Réutiliser les icônes dans trois contextes
Dans le bloc core/icon et l’API REST
Le sélecteur du bloc core/icon affiche automatiquement toutes les collections déclarées, puis le frontend rend l’icône choisie sans code complémentaire. WordPress expose aussi les icônes à l’endpoint REST /wp-json/wp/v2/icons et les collections à /wp-json/wp/v2/icon-collections, ce qui les rend disponibles aux outils externes qui lisent les données WordPress.
Dans PHP avec wp_get_icon()
wp_get_icon() renvoie le SVG sous forme de chaîne. Pour afficher le cœur dans un modèle, envoyez directement son résultat.
echo wp_get_icon( 'myplugin/heart' );Dans un modèle réel, passez un second tableau pour régler la taille, ajouter une classe CSS et fournir un libellé accessible.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizedéfinit la largeur et la hauteur du SVG en pixels.classajoute une classe CSS à l’élément SVG.labeldéfinitaria-labelpour les lecteurs d’écran.
Créez ce shortcode [myplugin_icon] pour insérer une icône dans une publication, une page ou un widget. Il nettoie le nom, la taille et la classe reçus, puis ne renvoie rien lorsque l’icône n’existe pas.
add_shortcode( 'myplugin_icon', 'myplugin_icon_shortcode' );
function myplugin_icon_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'name' => 'heart',
'text' => '',
'size' => 24,
'class' => '',
),
$atts
);
$icon = wp_get_icon(
'myplugin/' . sanitize_key( $atts['name'] ),
array(
'size' => absint( $atts['size'] ),
'class' => sanitize_html_class( $atts['class'] ),
)
);
if ( ! $icon ) {
return '';
}
return sprintf(
'<span>%s %s</span>',
$icon,
esc_html( $atts['text'] )
);
}[myplugin_icon name="heart" text="Hello World"]
[myplugin_icon name="star" text="Featured post" size="32"]
[myplugin_icon name="bookmark" text="Save for later" size="20"]L’icône s’affiche à côté du texte avec la taille indiquée par l’attribut size. Comme les SVG utilisent currentColor, ils récupèrent automatiquement la couleur du texte adjacent.
Comme icône d’un bloc
Vous pouvez remplacer le Dashicon par une icône déclarée dans la configuration de register_block_type(). Utilisez le nom complet, préfixe de collection inclus.
'icon' => 'warning', // Utilise un Dashicon'icon' => 'myplugin/star', // Utilise une icône SVG déclaréeL’outil d’insertion de blocs affiche alors votre SVG à la place d’un Dashicon générique. Cette intégration fonctionne avec les blocs enregistrés en JavaScript comme avec les blocs uniquement en PHP.
5. Adapter les SVG avec CSS
Les icônes s’intègrent par défaut, mais une intégration soignée les fait suivre la couleur du texte, l’échelle typographique et les états d’interaction. L’argument class de wp_get_icon() fournit un hook CSS pour les SVG rendus en PHP ; les règles appliquées à un conteneur couvrent aussi les icônes de l’éditeur, où cet argument n’intervient pas.
Hériter de la couleur avec currentColor
Préférez stroke="currentColor" ou fill="currentColor" à une couleur codée en dur. Dans un texte rouge, sombre ou dans un lien, le SVG adopte alors la couleur de son contexte et se comporte comme du texte.
<!-- Couleur codée en dur : l’icône reste toujours rouge. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Une icône sans couleur imposée s’adapte à tout thème, tandis qu’une icône à couleur fixe risque de jurer avec une partie d’entre eux.
Imposer ponctuellement une couleur
Pour un repère d’état ou une marque qui doit conserver sa couleur, définissez color sur le SVG grâce à sa classe. currentColor propage alors cette valeur vers le contour ou le remplissage.
.featured-icon {
color: #f59e0b; /* Ambre, quelle que soit la couleur du texte. */
}Gérer la taille et le survol
L’argument size règle directement la taille en pixels des SVG rendus par shortcode ou avec wp_get_icon(). Si vous devez piloter la taille en CSS ou animer le survol, ciblez le SVG dans son conteneur.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Utilisez
sizedanswp_get_icon()pour un cas isolé où une dimension précise compte et ne justifie pas une règle CSS. - Utilisez des classes CSS, via
classou via l’élément conteneur, lorsque l’icône apparaît à plusieurs endroits, doit garder une présentation uniforme ou dépend d’un état (hover,focus,active) ou d’un contexte, comme un lien ou un titre. - Dans le shortcode, ajustez les cas ponctuels avec l’attribut
sizeet assurez une cohérence à l’échelle du site avec une règle telle que.myplugin-icon-inline svg.
6. Retirer des icônes et nettoyer à la désactivation
WordPress 7.1 prévoit une fonction de désenregistrement pour une icône et une autre pour une collection entière. Pendant le développement, ou lorsqu’une mise à jour d’extension abandonne une icône, retirez-la ainsi :
wp_unregister_icon( 'myplugin/bookmark' );L’icône disparaît du sélecteur à la requête suivante. Les publications qui l’avaient déjà insérée dans un bloc core/icon produiront un rendu vide, car WordPress ne réécrit pas le contenu des publications.
À la désactivation de l’extension, désenregistrez la collection pour retirer toutes ses icônes d’un seul appel. Vous n’avez pas à boucler sur chaque icône.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Questions fréquentes
Faut-il déclarer une collection avant ses icônes ?
Oui. Une icône doit appartenir à une collection existante, sinon elle n’apparaît pas dans le sélecteur. Déclarez la collection sur init avec la priorité par défaut, puis les icônes avec une priorité plus élevée, telle que 20.
Peut-on mélanger content et file_path dans une collection ?
Oui. Chaque appel à wp_register_icon() reste indépendant : utilisez content pour une ou deux icônes et file_path pour les autres. Une fois déclarées, WordPress les traite de la même manière.
Les icônes personnalisées fonctionnent-elles dans register_block_type() ?
Oui. Passez le nom déclaré, par exemple 'myplugin/star', à la clé icon de register_block_type(). L’outil d’insertion affiche alors ce SVG au lieu d’un Dashicon, pour les blocs JavaScript comme pour les blocs uniquement en PHP.
wp_get_icon() renvoie-t-elle du HTML ou une chaîne ?
wp_get_icon() renvoie le SVG sous forme de chaîne : vous pouvez donc l’afficher avec echo ou l’envelopper dans votre propre HTML. Son second tableau $args accepte size, class, label pour aria-label et title.
Quels attributs SVG faut-il retirer avant l’enregistrement ?
Retirez les couleurs fill et stroke codées en dur, les attributs width et height du <svg> racine, ainsi que tout bloc <style> ou script. Conservez le viewBox et les attributs structurels, puis utilisez currentColor pour chaque référence de couleur.
Peut-on déclarer les icônes depuis un thème ?
Oui. Le même appel à wp_register_icon() fonctionne dans le fichier functions.php d’un thème en construisant le chemin avec get_stylesheet_directory(). En contrepartie, ces icônes disparaissent lorsque vous changez de thème.
Que se passe-t-il si deux collections utilisent le même nom d’icône ?
Les collections servent d’espace de noms : myplugin/heart et anotherplugin/heart coexistent sans conflit. C’est le nom complet, préfixe de collection compris, qui garantit l’unicité.
WordPress nettoie-t-il les SVG à l’enregistrement ?
Non. WordPress ne modifie pas le contenu SVG au moment de l’enregistrement : il sert exactement la chaîne ou le contenu de fichier que vous fournissez. Nettoyez vos SVG avant de les distribuer ; retirez scripts, références externes et tout élément inutile.
Préparer votre bibliothèque d’icônes
Commencez par déclarer la collection, choisissez content pour les rares SVG intégrés et file_path pour une bibliothèque de fichiers. Dès que le catalogue grandit, adoptez la boucle avec glob() : le même code passe de trois à plusieurs centaines d’icônes.
Une déclaration alimente simultanément l’éditeur, les modèles PHP et l’API REST. En associant cette API à vos blocs personnalisés, vous pouvez fournir une expérience d’éditeur identifiée à votre extension sans étape de build JavaScript.
Antoine Martin
Ingénieur DevSecOps, spécialiste des pratiques de développement sécurisé et des pipelines CI/CD. Docker et GitHub Actions font partie de mon quotidien.
Tous les articles
