Kako registrirati prilagođene SVG ikone u WordPressu 7.1
Prilagođene SVG ikone u blok editoru dosad su obično tražile JavaScript, build korak ili nepouzdano privremeno rješenje. WordPress 7.1 donosi javni API s kojim iz dodatka možete registrirati vlastite ikone, prikazati ih u biraču bloka core/icon, ispisati ih u PHP-u i dohvatiti preko REST API-ja – bez JavaScripta i bez build procesa.
WordPress 7.1 treba izaći 19. kolovoza 2026. Za razvoj možete koristiti i izdanje 7.1 RC, a primjeri u nastavku odgovaraju API-ju koji se očekuje u konačnom izdanju. Izradit ćete dodatak s kolekcijom myplugin, ikonom srca definiranoj u PHP-u te ikonama zvijezde i oznake knjižne stranice koje se učitavaju iz .svg datoteka.
Preduvjeti
Za rad trebate WordPress 7.1 ili noviji, nekoliko SVG datoteka, lokalno razvojno okruženje kao što su LocalWP, WordPress Studio ili wp-env te osnovno znanje PHP-a.
API se svodi na kolekcije i tri funkcije
Svaka ikona pripada kolekciji, odnosno imenovanom skupu ikona. Naziv kolekcije postaje prefiks naziva ikone: zato se core/plus razlikuje od myplugin/plus, a ikone različitih dodataka ne sudaraju se s WordPress core ikonama niti međusobno.
wp_register_icon_collection( $name, $args )registrira imenovanu kolekciju.wp_register_icon( $name, $args )registrira pojedinu ikonu.wp_get_icon( $name, $args )vraća SVG ikone kao string koji možete ispisati u PHP-u.
Pri registraciji SVG možete proslijediti na dva načina. Argument content sadrži SVG markup kao string ugrađen izravno u PHP, dok file_path prima apsolutnu putanju do .svg datoteke na disku. Za pojedinu ikonu koristite samo jedan od tih argumenata: content odgovara za jednu ili dvije ikone, a file_path lakše održava veću mapu ikona.
1. Postavite dodatak i najprije registrirajte kolekciju
Kolekciju morate registrirati prije ikona. Ako pokušate registrirati ikonu za kolekciju koja još ne postoji, ona se neće pojaviti u biraču ikona i WordPress neće prikazati očitu pogrešku.
U mapi wp-content/plugins/ izradite sljedeću strukturu:
myplugin/
├── myplugin.php
└── icons/
├── star.svg
└── bookmark.svgDatoteka dodatka najprije definira putanju i kolekciju. Kolekciju vežite na init sa zadanom prioritetom 10; ikone ćete registrirati kasnije, s prioritetom 20.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registrira prilagođene SVG ikone za 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' ),
)
);
}Naziv myplugin sada prefiksira sve ikone iz dodatka, primjerice myplugin/heart, myplugin/star i myplugin/bookmark. Argument label postaje naslov odjeljka u biraču ikona. Aktivirajte dodatak kroz Dodaci → Instalirani dodaci; sama kolekcija neće prikazati ništa dok joj ne dodate ikone.
2. Registrirajte ikone iz PHP-a i datoteka
Možete kombinirati oba načina registracije u istoj kolekciji. U primjeru srce registriramo preko content, a zvijezdu i oznaku knjižne stranice preko file_path.
Ikona ugrađena u PHP
Kad imate samo nekoliko ikona, SVG možete držati izravno u datoteci dodatka. Ikona se registrira na init s prioritetom 20, pa kolekcija sigurno već postoji.
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>',
)
);
}Puni naziv myplugin/heart prati oblik kolekcija/slug-ikone, a label se prikazuje u biraču. Atribut stroke="currentColor" posebno je važan: ikona nasljeđuje boju okolnog teksta umjesto da ima fiksnu boju.
Ikone učitane iz .svg datoteka
Za ikone na disku spremite sljedeće datoteke u mapu icons/. WordPress će ih čitati po potrebi.
<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>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',
)
);
}Jedina promjena u odnosu na ugrađeni SVG jest zamjena argumenta content argumentom file_path. Otvorite blok core/icon u editoru: birač će prikazati odjeljak MyPlugin s ikonama Heart, Star i Bookmark. Ako ikona nedostaje, najprije provjerite redoslijed registracije – kolekcija mora biti na zadanoj prioriteti, a ikone nakon nje, primjerice na 20.
3. Automatski registrirajte cijelu mapu
Ručno pozivanje wp_register_icon() za trideset ikona brzo postaje neodrživo. Umjesto pojedinačne funkcije myplugin_register_file_icons() koristite glob() da PHP na svakom zahtjevu pronađe sve SVG datoteke u mapi i registrira svaku od njih.
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' )vraća sve.svgdatoteke iz mape.basename( $file_path, '.svg' )uzima naziv bez ekstenzije, paadvanced-button.svgpretvara uadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )iz sluga stvara čitljivu oznaku za birač:advanced-buttonpostaje „Advanced Button“.- Petlja svaku datoteku registrira u kolekciji s prefiksom
myplugin/.
Dodajte novu SVG datoteku u icons/, osvježite editor i ikona će se pojaviti bez izmjene PHP-a. Ovaj obrazac jednako radi s nekoliko ikona i cijelom bibliotekom: srce može ostati definirano ugrađeno, dok se zvijezda, oznaka knjižne stranice i sve naknadne datoteke učitavaju iz mape.
4. Iskoristite iste ikone u editoru, PHP-u i blokovima
Nakon registracije ista je ikona dostupna u tri konteksta. Blok core/icon automatski prikazuje sve registrirane kolekcije, pa urednik može odabrati ikonu koja se zatim prikazuje i na frontend strani bez dodatnog koda.
REST API također izlaže ikone na endpointu /wp-json/wp/v2/icons, a kolekcije na /wp-json/wp/v2/icon-collections. Vanjski alati koji čitaju podatke WordPressa, uključujući AI agente, tako mogu otkriti iste registrirane ikone.
Ispis ikone u PHP predlošku
Funkcija wp_get_icon() vraća SVG string. Najjednostavniji ispis izgleda ovako:
echo wp_get_icon( 'myplugin/heart' );Drugi argument omogućuje da odredite veličinu, CSS klasu i pristupačnu oznaku.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizepostavljawidthiheightSVG-a u pikselima.classdodaje CSS klasu elementu SVG.labelpostavljaaria-labelza čitače zaslona.
Uz size, class i label, polje $args podržava i title. Budući da funkcija vraća string, možete ga odmah ispisati s echo ili umetnuti u vlastiti HTML.
Kratki kod za sadržaj objava
Sljedeći kratki kod [myplugin_icon] dopušta autorima da umeću registriranu ikonu uz tekst u objave, stranice i widgete. Sanitizacija naziva, veličine i klase ostaje važna i kada ikone dolaze iz vlastitog dodatka.
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"]Ikona će stajati uz tekst i preuzet će veličinu iz atributa size. Kako SVG koristi currentColor, automatski će naslijediti i boju okolnog teksta.
Ikona kao oznaka vlastitog bloka
Prilagođena ikona može zamijeniti zadani Dashicon pri registraciji bloka. Umjesto naziva ugrađene ikone kao što je warning, ključu icon proslijedite puni registrirani naziv.
'icon' => 'warning', // Koristi Dashicon
// Umjesto toga:
'icon' => 'myplugin/star', // Koristi registriranu prilagođenu ikonuInserter blokova tada prikazuje vaš SVG umjesto generičkog Dashicona. Taj pristup radi i s blokovima koje registrirate JavaScriptom i s blokovima koje registrirate samo u PHP-u.
5. Oblikujte ikone tako da se uklope u temu
SVG će se prema zadanim postavkama uklopiti u WordPress, ali dobra integracija traži da reagira na boju teksta, veličinu fonta i stanja kao što je prelazak pokazivača. Klasa proslijeđena kroz wp_get_icon() daje izravnu CSS poveznicu, dok stilove za blok editor možete pisati preko omotača i selektora jer tamo argument class nije nužno dostupan.
Naslijedite boju s currentColor
U SVG-u koristite stroke="currentColor" ili fill="currentColor", a ne fiksne vrijednosti boje. Ikona će tako biti crvena unutar crvenog teksta, prilagodit će se tamnoj temi te odgovarati boji poveznice – ponašat će se kao tekst.
<!-- Ne koristite fiksnu boju: ikona bi uvijek bila crvena -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Ovaj izbor odlučuje hoće li se ikona uklopiti u bilo koju temu ili će se sukobiti s dijelom tema. Prije registracije uklonite fiksne atribute fill i stroke, kao i width i height na korijenskom elementu <svg>; viewBox zadržite. Uklonite i sve blokove <style>, skripte, vanjske reference te sve što ikoni nije potrebno, ali sačuvajte viewBox i strukturne atribute.
SVG morate sami sanitizirati
WordPress pri registraciji ne mijenja ni ne sanitizira SVG. Poslužuje točan string iz argumenta content odnosno sadržaj datoteke na koju pokazuje file_path. Prije isporuke sami očistite SVG: uklonite skripte, vanjske reference i nepotreban sadržaj.
Nametnite boju kada je to nužno
Statusna ikona ili oznaka brenda ponekad mora zadržati određenu boju bez obzira na okruženje. Ako SVG koristi currentColor, postavite CSS svojstvo color na SVG-u preko klase; vrijednost će se prenijeti na njegov stroke ili fill.
.featured-icon {
color: #f59e0b; /* Jantarna boja, neovisno o okolnom tekstu */
}Veličina i stanje pri prelasku pokazivača
Za ikone dobivene s kratkim kodom ili wp_get_icon() argument size izravno postavlja veličinu u pikselima. Kada veličinu ili ponašanje želite kontrolirati CSS-om, primjerice na hover, stilizirajte SVG u omotaču.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Koristite
sizeuwp_get_icon()za pojedinačan slučaj u kojem vam treba točna veličina u pikselima i nema smisla pisati CSS. - Koristite CSS klase, kroz argument
classili na elementu omotača, kada se ikona pojavljuje na više mjesta, mora ostati dosljedna ili stil ovisi o stanju poput hovera, fokusa i aktivnog stanja odnosno o kontekstu poput poveznice ili naslova. - U kratkom kodu manje pojedinačne izmjene riješite atributom
size, a dosljedan stil za cijelu stranicu postavite pravilima za.myplugin-icon-inline svg.
6. Uklonite ikonu ili cijelu kolekciju
WordPress 7.1 ima par funkcija za odjavu: wp_unregister_icon() za pojedinu ikonu i wp_unregister_icon_collection() za cijelu kolekciju. Pojedinu ikonu možete ukloniti tijekom razvoja ili kada je nova verzija dodatka više ne isporučuje.
wp_unregister_icon( 'myplugin/bookmark' );Ikona će nestati iz birača pri sljedećem zahtjevu. Objave koje su već umetnule tu ikonu kroz blok core/icon prikazat će prazno mjesto jer WordPress ne prepisuje sadržaj postojećih objava.
Pri deaktivaciji dodatka odjavite cijelu kolekciju. Time se jednim pozivom uklanjaju sve ikone iz nje, bez prolaska kroz pojedine nazive.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Odgovori na česta pitanja
Mora li kolekcija postojati prije registracije ikona?
Mora. Ikone pripadaju postojećoj kolekciji; inače se tiho neće pojaviti u biraču. Registrirajte kolekciju na init sa zadanom prioritetom, a ikone s većim prioritetom, primjerice 20.
Smijete li miješati content i file_path u istoj kolekciji?
Smijete. Svaki poziv wp_register_icon() neovisan je o drugima: content koristite za jednu ili dvije ikone, a file_path za ostale. Nakon registracije WordPress ih tretira jednako.
Rade li prilagođene ikone kao ikone blokova u register_block_type()?
Rade. Ključu icon u register_block_type() dodijelite registrirani naziv, primjerice 'myplugin/star'. Inserter će tada prikazati prilagođeni SVG umjesto Dashicona, i to za blokove registrirane JavaScriptom te blokove registrirane samo PHP-om.
Možete li ikone registrirati iz teme umjesto iz dodatka?
Možete. Isti poziv wp_register_icon() radi u datoteci functions.php teme, a putanju do datoteka možete dobiti s get_stylesheet_directory(). Kompromis je što ikone registrirane iz teme nestaju kada promijenite temu.
Što ako dvije kolekcije imaju ikonu istog naziva?
Kolekcije služe kao imenski prostori, pa myplugin/heart i anotherplugin/heart mogu postojati bez sukoba. Jedinstven je puni naziv koji uključuje prefiks kolekcije.
Što primijeniti u dodatku
Ovaj API slijedi obrazac „registrirajte jednom, koristite svugdje”: ista registracija opslužuje editor, PHP, REST API i vanjske alate. Odgovara širem smjeru WordPressovih temeljnih API-ja, uključujući Abilities API, blokove i block bindings, koji dodatku omogućuju integraciju s editorom, REST slojem i alatima izgrađenima nad podatkovnim modelom WordPressa.
Za vlastiti dodatak najprije registrirajte kolekciju, zatim odaberite content za malu količinu ugrađenih SVG-ova ili file_path za datoteke, a za veću biblioteku prijeđite na glob(). Zadržite viewBox, koristite currentColor, sami sanitizirajte SVG i planirajte što se događa sa sadržajem objava prije nego što odjavite već korištenu ikonu. Potpuni primjer dodatka sa SVG datotekama, README-om i obrascem grupne registracije dostupan je na GitHubu.
Reference / Izvori
Ivana Babić
WordPress multisite i mrežna administratorica. Upravljanje velikim WordPress instalacijama je moja specijalnost. Skalabilnost i sigurnost iznad svega.
Svi članci
