WordPress 7.1 Icon Registration API: come registrare icone SVG personalizzate

Con WordPress 7.1 diventa disponibile un’API pubblica per registrare collezioni di icone SVG e renderle utilizzabili nell’Icon block. Le stesse icone possono essere richiamate anche da PHP e consultate attraverso endpoint REST di sola lettura.

Per web agency e freelance significa poter gestire le icone di progetto in modo più controllato, evitando di inserire manualmente lo stesso SVG in punti diversi. Considerare questa API come infrastruttura di un design system consegnabile al cliente è però un’interpretazione applicativa: non è una caratteristica dichiarata dell’API.

Che cos’è la WordPress Icon Registration API

La WordPress Icon Registration API introduce un flusso pubblico per registrare:

• una collezione identificata da uno slug univoco;
• una o più icone associate alla collezione;
• il markup SVG inline oppure il percorso del relativo file;
• etichette e descrizioni traducibili mostrate nell’interfaccia.

Le collezioni registrate compaiono come schede nella libreria dell’Icon block, accanto alla raccolta core. L’editor può quindi selezionare un’icona senza dover incollare direttamente il relativo markup.

In un progetto per un cliente, questo permette potenzialmente di trasformare un insieme di asset grafici in una libreria editoriale coerente. Non implica, tuttavia, che l’API sostituisca sempre librerie esterne o componenti proprietari: può ridurne la necessità soltanto in alcuni progetti.

Come registrare una collezione e le relative icone

La registrazione deve essere eseguita sull’hook init. L’ordine delle operazioni è importante:

1. registrare la collezione con wp_register_icon_collection();
2. registrare le singole icone con wp_register_icon().

Gli slug possono contenere lettere minuscole, numeri, trattini e underscore. È consigliabile usare un prefisso collegato al plugin, al tema o al progetto, così da ridurre il rischio di collisioni.

L’identificatore di ogni icona deve rispettare il formato collezione/nome-icona. Per esempio:

agenzia/analytics

Il nome della collezione precede lo slash, mentre la seconda parte identifica l’icona al suo interno. Le stringhe destinate all’interfaccia, come label e description, devono essere rese traducibili con le funzioni di internazionalizzazione di WordPress.

Esempio di registrazione con wp_register_icon()

Questo esempio registra una collezione e carica l’icona Analytics da un file incluso nel plugin:

<?php
add_action( 'init', 'agenzia_register_icons' );

function agenzia_register_icons(): void {
    if ( ! function_exists( 'wp_register_icon' ) ) {
        return;
    }

    wp_register_icon_collection(
        'agenzia',
        array(
            'label'       => __( 'Agenzia', 'agenzia' ),
            'description' => __( 'Icone personalizzate del progetto.', 'agenzia' ),
        )
    );

    wp_register_icon(
        'agenzia/analytics',
        array(
            'label'     => __( 'Analytics', 'agenzia' ),
            'file_path' => plugin_dir_path( __FILE__ ) . 'icons/analytics.svg',
        )
    );
}

wp_register_icon() richiede una label e uno solo tra questi due parametri:

• content, per fornire direttamente il markup SVG;
• file_path, per indicare il percorso di un file SVG.

content può risultare pratico per esempi isolati o icone definite direttamente nel codice. file_path permette invece di mantenere gli SVG in file separati.

Il file indicato tramite file_path viene caricato quando il contenuto dell’icona è effettivamente richiesto. Un percorso errato, quindi, potrebbe non manifestarsi durante la registrazione e produrre successivamente un output vuoto.

Durante lo sviluppo è opportuno verificare i valori restituiti dalle funzioni e gli eventuali avvisi _doing_it_wrong(), in particolare per nomi invalidi, registrazioni duplicate o configurazioni incomplete.

Come usare le icone nell’Icon block e in PHP

Inserimento nell’Icon block

Dopo la registrazione, la nuova collezione è disponibile nella libreria dell’Icon block. Il markup del blocco per l’esempio precedente è:

<!-- wp:icon {"icon":"agenzia/analytics"} /-->

L’identificatore memorizzato dal blocco contiene sia lo slug della collezione sia quello dell’icona.

Rendering tramite PHP

Per ottenere l’SVG sanitizzato da PHP è disponibile wp_get_icon(). La funzione supporta principalmente gli argomenti size, class e label:

<?php
echo wp_get_icon(
    'agenzia/analytics',
    array(
        'size'  => 32,
        'class' => 'icona-analytics',
        'label' => __( 'Visualizza i dati Analytics', 'agenzia' ),
    )
);

La dimensione predefinita indicata è 24 pixel. Se l’icona non ha una label, viene trattata come decorativa. Se invece l’identificatore richiesto non è registrato, wp_get_icon() restituisce una stringa vuota.

È importante testare il risultato sia nell’editor sia nel frontend. L’Icon block applica fill: currentColor, mentre un’icona renderizzata autonomamente con wp_get_icon() potrebbe richiedere una regola CSS esplicita:

.icona-analytics {
    fill: currentColor;
}

Limiti SVG e checklist di compatibilità

La disponibilità di un’API pubblica non significa che qualsiasi file SVG possa essere registrato senza modifiche. In WordPress 7.1 la sanitizzazione descritta è restrittiva e rende più adatte le icone semplici costruite con forme piene.

L’allowlist conserva questi elementi:

• <svg>;
• <path>;
• <polygon>.

Elementi comuni come <circle> e <rect> vengono rimossi. Sono rimossi anche script, event handler, stili non ammessi e l’attributo stroke. Le icone outline basate sugli stroke non devono quindi essere considerate automaticamente compatibili.

Anche il comportamento di fill richiede attenzione: il valore applicato all’elemento <svg> esterno non sopravvive, mentre è ammesso su <path> e <polygon>. Per seguire il colore del testo si può usare fill="currentColor" sulle forme oppure assegnare una classe con la stessa proprietà CSS.

Checklist prima della registrazione

• eliminare metadati non necessari;
• rimuovere script, event handler e stili inline non ammessi;
• semplificare le trasformazioni superflue;
• convertire gli stroke in tracciati pieni;
• evitare di basare l’icona su <circle> o <rect>;
• usare preferibilmente <path> e <polygon>;
• controllare il risultato sanitizzato nel frontend e nell’editor;
• verificare il colore con il CSS effettivo del progetto.

Consultazione tramite REST API

WordPress 7.1 espone sotto wp/v2 endpoint REST per consultare:

• le collezioni registrate;
• l’elenco delle icone;
• le icone appartenenti a una determinata collezione;
• una singola icona.

Gli endpoint descritti sono di sola lettura e richiedono un utente autenticato con capacità editoriali. Non consentono di creare o modificare le icone e non devono essere presentati come un sistema di gestione remota della libreria.

Come integrare l’API nei progetti delle web agency

Per una web agency o un freelance, una possibile organizzazione consiste nel raccogliere le icone di brand in un plugin dedicato. In questo modo possono restare disponibili anche quando cambia il tema. È una raccomandazione progettuale, non un requisito tecnico dell’API.

Un flusso operativo può prevedere:

1. raccolta e normalizzazione degli SVG forniti dal cliente;
2. verifica degli elementi compatibili con la sanitizzazione;
3. assegnazione di slug prefissati e coerenti;
4. registrazione della collezione e delle icone su init;
5. test nell’Icon block e nel frontend;
6. documentazione delle icone disponibili per chi gestisce i contenuti.

Per plugin o temi che devono funzionare anche con versioni precedenti, occorre richiedere WordPress 7.1 oppure verificare la presenza della funzione:

function_exists( 'wp_register_icon' )

In WordPress 7.1 non è disponibile un componente pubblico e stabile per riutilizzare liberamente il picker dell’Icon block all’interno di qualsiasi blocco personalizzato. Una libreria registrata può essere usata nell’Icon block, ma questo non equivale alla disponibilità di un picker generico per altre interfacce.

Domande frequenti

Quali elementi SVG sono supportati dalla WordPress Icon Registration API?

Nell’allowlist descritta per WordPress 7.1 vengono conservati <svg>, <path> e <polygon>. Elementi come <circle> e <rect> vengono rimossi, così come script, event handler, stili non ammessi e l’attributo stroke.

Qual è la differenza tra content e file_path in wp_register_icon()?

content contiene direttamente il markup SVG, mentre file_path indica il percorso del file SVG. Per registrare un’icona bisogna usare uno solo dei due. Con file_path il caricamento è differito fino alla richiesta del contenuto.

Come si mostra un’icona registrata tramite PHP?

Si usa wp_get_icon() indicando l’identificatore nel formato collezione/nome-icona. La funzione restituisce l’SVG sanitizzato e supporta principalmente dimensione, classe e label. Un identificatore non registrato produce una stringa vuota.

Le icone registrate sono disponibili nell’Icon block?

Sì. Le collezioni registrate appaiono nella libreria dell’Icon block accanto alla raccolta core e le icone possono essere selezionate dall’editor.

È possibile riutilizzare il picker delle icone in un blocco personalizzato?

In WordPress 7.1 non esiste un componente pubblico e stabile che permetta di riutilizzare il picker dell’Icon block in qualsiasi blocco personalizzato.

Gli endpoint REST permettono di creare o modificare le icone?

No. Gli endpoint indicati sotto wp/v2 sono di sola lettura e servono a consultare collezioni e icone registrate. Richiedono inoltre un utente autenticato con capacità editoriali.

Una libreria SVG pronta per il flusso editoriale

La WordPress Icon Registration API offre una base pubblica per rendere le icone personalizzate disponibili nell’editor e nel codice PHP. Il risultato dipende però dalla preparazione degli SVG: forme piene, markup essenziale e test dopo la sanitizzazione sono passaggi centrali per un’integrazione affidabile.

Posso supportarti nella progettazione di una libreria SVG compatibile, nella sua registrazione tramite plugin e nell’integrazione nel flusso editoriale del cliente.

Contattami per saperne di più.

Fonte

Hands-on with the WordPress 7.1 Icon Registration API — WordPress Developer Blog