Come registrare icone SVG personalizzate in WordPress 7.1
Con WordPress 7.1 puoi registrare icone SVG personalizzate in PHP, senza JavaScript né build step. Una volta registrate, il selettore del blocco core/icon, i template PHP e la REST API leggono la stessa libreria.
La versione 7.1 è prevista per il 19 agosto 2026. Puoi già sviluppare con la release candidate, purché lavori in un ambiente locale e conosca le basi di PHP.
Cosa creerai
Costruirai un plugin chiamato myplugin-custom-icons che registra una collezione di icone chiamata myplugin. La libreria includerà un cuore definito direttamente nel codice PHP, una stella e un segnalibro caricati da file .svg.
Vedrai anche come registrare automaticamente tutti gli SVG di una cartella, inserire un’icona nel contenuto con uno shortcode e usare un’icona registrata come icona di un blocco, incluso un blocco registrato solo in PHP.
Prerequisiti
Prima di iniziare, prepara questi elementi:
- WordPress 7.1 o successivo; per lo sviluppo va bene anche WordPress 7.1 RC.
- Alcuni file di icone SVG, oppure i file di esempio inclusi nei passaggi successivi.
- Un ambiente locale, come LocalWP, WordPress Studio o wp-env.
- Conoscenze di base di PHP.
Le tre funzioni dell’API
L’API delle icone personalizzate di WordPress 7.1 ruota attorno a tre funzioni e alle collezioni. Una collezione è un gruppo nominato di icone: ogni icona deve appartenerne a una.
wp_register_icon_collection( $name, $args ): registra una collezione con un nome.wp_register_icon( $name, $args ): registra una singola icona.wp_get_icon( $name, $args ): genera l’SVG in PHP e restituisce una stringa SVG.
Il nome della collezione diventa il prefisso dell’icona. Per esempio, core/plus e myplugin/plus sono nomi distinti: questo namespace evita conflitti con le icone del core e con quelle di altri plugin.
Quando registri un’icona, passa il markup SVG nella proprietà content oppure il percorso assoluto di un file nella proprietà file_path, mai entrambe. content è pratico per una o due icone; file_path è più adatto a una libreria in una cartella.
1. Crea il plugin e registra la collezione
Registra prima la collezione e poi le icone. Se tenti di registrare un’icona in una collezione inesistente, non comparirà nel selettore senza mostrare errori.
Crea questa struttura in wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgNel file principale aggiungi l’header del plugin, proteggi l’accesso diretto e registra la collezione sull’hook init con la priorità predefinita, cioè 10.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registra icone SVG personalizzate per 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__ ) );
/**
* Registra la collezione di icone.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Il nome myplugin prefissa tutte le icone della collezione, per esempio myplugin/heart e myplugin/star. La proprietà label diventa l’intestazione della sezione nel selettore delle icone.
Attiva il plugin da Plugin → Plugin installati. A questo punto non vedrai ancora alcun risultato: una collezione vuota non genera elementi nell’interfaccia.
2. Registra le icone con content e file_path
Puoi combinare i due metodi nella stessa collezione. Registra il cuore con content, quindi carica stella e segnalibro dai rispettivi file SVG.
Definisci un SVG inline
Con content mantieni l’SVG direttamente nel file PHP. È un’opzione comoda quando hai poche icone e non vuoi creare file aggiuntivi.
/**
* Registra un'icona con SVG inline.
*/
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>',
)
);
}La priorità 20 esegue questa registrazione dopo quella della collezione. Il nome segue il formato collezione/slug-icona; label compare nel selettore e content contiene il markup SVG. L’attributo stroke="currentColor" fa ereditare all’icona il colore del testo circostante, senza fissare un colore nello SVG.
Carica SVG dalla cartella del plugin
Salva questi file nella cartella icons/. Entrambi conservano viewBox e usano currentColor per adattarsi al contesto grafico.
<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>Ora registra i due file con file_path. WordPress leggerà ogni file quando serve.
/**
* Registra le icone dai file SVG.
*/
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',
)
);
}Apri il blocco core/icon nell’editor: il selettore mostrerà una sezione MyPlugin con Heart, Star e Bookmark. Se un’icona manca, controlla anzitutto l’ordine di registrazione: registra la collezione alla priorità predefinita e le icone alla priorità 20.
core/icon. — Forrás: WPVibes3. Registra automaticamente un’intera cartella
Registrare trenta icone con trenta chiamate a wp_register_icon() non è sostenibile. Sostituisci la funzione myplugin_register_file_icons() con questa variante: cerca tutti gli SVG nella cartella e registra ciascun file alla richiesta successiva.
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' )restituisce tutti i file.svgnella cartella.basename( $file_path, '.svg' )estrae il nome senza estensione:advanced-button.svgdiventaadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )trasforma lo slug in un’etichetta leggibile:advanced-buttondiventaAdvanced Button.- Il ciclo registra ogni icona nella collezione
myplugin/.
Aggiungi un SVG alla cartella icons/, aggiorna l’editor e l’icona apparirà nel selettore senza modificare il codice. Questo schema scala dall’insieme di esempio – cuore inline, stella, segnalibro – a centinaia di file.
4. Usa le icone nell’editor, in PHP e nei blocchi
Nel blocco core/icon e nella REST API
Il selettore del blocco core/icon mostra automaticamente ogni collezione registrata. Chi modifica una pagina può inserire l’icona e WordPress la renderà nel frontend, senza codice aggiuntivo.
Le icone sono disponibili anche nell’endpoint REST /wp-json/wp/v2/icons; l’endpoint complementare /wp-json/wp/v2/icon-collections espone le collezioni. Strumenti esterni che leggono i dati di WordPress, inclusi gli agenti AI, possono quindi scoprirle.
Nei template PHP con wp_get_icon()
wp_get_icon() restituisce l’SVG come stringa. Nel caso più semplice puoi stamparla direttamente:
echo wp_get_icon( 'myplugin/heart' );Nei template passa il secondo array per controllare dimensione, classe CSS e accessibilità:
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizeimpostawidtheheightdell’SVG in pixel.classaggiunge una classe CSS all’elemento SVG.labelimpostaaria-labelper i lettori di schermo.
Inserisci le icone nel contenuto con uno shortcode
Questo shortcode [myplugin_icon] permette di aggiungere un’icona a articoli, pagine e widget. Sanifica il nome dell’icona, la dimensione e la classe prima di passarli a wp_get_icon().
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 class="myplugin-icon-inline">%s %s</span>',
$icon,
esc_html( $atts['text'] )
);
}Usalo così:
[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’icona comparirà accanto al testo con la dimensione indicata da size. Grazie a currentColor, erediterà automaticamente il colore del testo che la circonda.
Come icona di un blocco registrato
Nella configurazione di register_block_type(), una chiave icon può usare un Dashicon predefinito:
'icon' => 'warning', // Usa un DashiconCon WordPress 7.1 passa invece il nome completo di un’icona registrata:
'icon' => 'myplugin/star', // Usa un'icona SVG personalizzataL’inseritore dei blocchi mostrerà l’SVG personalizzato al posto del Dashicon generico. Questa modalità funziona sia per i blocchi registrati con JavaScript sia per quelli registrati solo in PHP.
5. Adatta le icone con CSS
Un’icona integrata bene eredita il colore del testo, scala insieme al contesto e può cambiare stato al passaggio del mouse. Usa stroke="currentColor" oppure fill="currentColor" al posto di un colore fisso nello SVG.
<!-- Colore fisso: l'icona resterà sempre rossa -->
<svg viewBox="0 0 24 24"
stroke="#dc2626"
stroke-width="2">
<path d="..."/>
</svg>Con currentColor, l’icona dentro un testo rosso diventa rossa, in un tema scuro assume il colore adatto e in un link usa il colore del link. Un SVG senza colori rigidi si adatta ai temi; un SVG con colori fissati può entrare in conflitto con molti di essi.
Se un’icona deve mantenere un colore specifico, per esempio per un marchio o un indicatore di stato, imposta color via CSS. Poiché lo SVG usa currentColor, il valore si propaga a stroke o fill.
.featured-icon {
color: #f59e0b; /* Ambra, indipendente dal testo circostante */
}Per le icone generate dallo shortcode o da wp_get_icon(), size definisce direttamente la dimensione in pixel. Per affidare dimensione e stati al CSS, usa il wrapper dello shortcode oppure una classe passata tramite l’argomento class.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Usa
sizeinwp_get_icon()per casi isolati in cui serve una misura esatta in pixel e non vale la pena scrivere CSS. - Usa classi CSS, tramite l’argomento
classo sull’elemento wrapper, quando l’icona ricorre in più punti e deve restare coerente, oppure quando lo stile dipende da stato – hover, focus, active – o contesto, come un link o un titolo. - Nello shortcode puoi applicare piccole variazioni con l’attributo
size; per una coerenza globale applica il CSS a.myplugin-icon-inline svg.
6. Rimuovi icone e collezioni
WordPress 7.1 include una funzione per rimuovere una singola icona e una per rimuovere un’intera collezione.
Rimuovi una sola icona
Durante lo sviluppo o quando un aggiornamento elimina un’icona, chiama wp_unregister_icon():
wp_unregister_icon( 'myplugin/bookmark' );L’icona scomparirà dal selettore alla richiesta successiva. Se un articolo contiene già quell’icona in un blocco core/icon, il blocco verrà renderizzato vuoto: WordPress non riscrive il contenuto degli articoli.
Rimuovi la collezione quando disattivi il plugin
Alla disattivazione del plugin, rimuovi la collezione per togliere tutte le sue icone dal selettore. Non devi iterare sulle singole icone.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Domande frequenti
Devo registrare una collezione prima delle icone?
Sì. Ogni icona deve appartenere a una collezione già esistente, altrimenti non apparirà nel selettore. Registra la collezione su init con la priorità predefinita, quindi registra le icone con una priorità più alta, come 20.
Posso mescolare icone content e file_path nella stessa collezione?
Sì. Ogni chiamata a wp_register_icon() è indipendente: usa content per una o due icone e file_path per le altre. Dopo la registrazione, WordPress le tratta nello stesso modo.
Le icone personalizzate funzionano in register_block_type()?
Sì. Assegna il nome dell’icona registrata, per esempio 'myplugin/star', alla chiave icon di register_block_type(). L’inseritore mostrerà l’SVG personalizzato invece di un Dashicon; la soluzione funziona sia con blocchi JavaScript sia con blocchi solo PHP.
wp_get_icon() restituisce HTML o una stringa?
wp_get_icon() restituisce l’SVG come stringa, quindi puoi stamparla direttamente con echo oppure avvolgerla nel tuo HTML. Il secondo array $args accetta size, class, label, che imposta aria-label, e title.
Quali attributi SVG devo eliminare prima della registrazione?
Rimuovi i colori fill e stroke fissati, gli attributi width e height dall’elemento radice <svg> – conserva viewBox – e qualsiasi blocco <style> o script. Mantieni viewBox e gli attributi strutturali, quindi usa currentColor per ogni riferimento al colore.
Posso registrare icone da un tema invece che da un plugin?
Sì. La chiamata a wp_register_icon() funziona anche nel file functions.php del tema, usando get_stylesheet_directory() per costruire il percorso dei file. Tieni presente che le icone registrate dal tema scompaiono quando cambi tema.
Cosa accade se due collezioni hanno un’icona con lo stesso nome?
Le collezioni isolano i nomi: myplugin/heart e anotherplugin/heart possono coesistere senza conflitti. L’identificatore univoco è il nome completo, prefisso della collezione incluso.
WordPress sanifica gli SVG durante la registrazione?
No. WordPress non modifica il contenuto SVG durante la registrazione: serve esattamente la stringa fornita o il contenuto del file indicato. Sanifica gli SVG prima della distribuzione, rimuovendo script, riferimenti esterni e tutto ciò che non è necessario.
Registra una volta e riusa ovunque
Questa API segue un modello comune alle API fondamentali di WordPress: registri una risorsa una sola volta e il sistema la rende individuabile nei diversi livelli della piattaforma. Il blocco core/icon, wp_get_icon() e la REST API leggono tutti dallo stesso registro.
Per il plugin, parti dalla collezione, scegli content per pochi SVG e file_path con glob() per una libreria estesa. Verifica gli SVG prima di distribuirli, usa currentColor e aggiorna a WordPress 7.1 quando la versione sarà disponibile per portare icone, blocchi e template nello stesso flusso PHP.
Riferimenti / Fonti
Francesca Rossi
Caporedattrice del team italiano, specialista in design system e librerie di componenti. Non posso vivere senza Figma e Storybook. Il mio obiettivo è un'interfaccia utente coerente.
Tutti gli articoli
