Vlastní SVG ikony ve WordPressu 7.1: kompletní návod pro pluginy
Vlastní ikony v blokovém editoru dosud obvykle znamenaly JavaScript, build krok nebo nespolehlivé náhradní řešení. WordPress 7.1, který vyjde 19. srpna 2026, přidává veřejné API pro vlastní SVG ikony: zaregistruješ je v pluginu, vybereš v bloku core/icon, vyrenderuješ v PHP a najdeš je také přes REST API – bez buildu JavaScriptu.
V návodu vytvoříš plugin se sbírkou ikon, přidáš ikony jako vložené SVG i jako soubory, automaticky načteš celou složku a ikony použiješ v šablonách, obsahu i jako symbol vlastního bloku. Pro vývoj potřebuješ WordPress 7.1 nebo 7.1 RC, lokální prostředí jako LocalWP, WordPress Studio či wp-env, několik SVG souborů a základní znalost PHP.
Jak API vlastních ikon funguje
API stojí na třech funkcích a na sbírkách ikon. Sbírka odděluje jmenné prostory: core/plus a myplugin/plus proto mohou existovat vedle sebe, aniž by se střetly s ikonami WordPress core nebo jiného pluginu.
wp_register_icon_collection( $name, $args )zaregistruje pojmenovanou sbírku ikon.wp_register_icon( $name, $args )přidá jednu ikonu.wp_get_icon( $name, $args )vrátí SVG ikony jako řetězec, který můžeš vyrenderovat v PHP.
Každá ikona musí patřit do existující sbírky a její celé jméno má tvar sbirka/slug-ikony. SVG předáš buď přes content jako řetězec přímo v PHP, nebo přes file_path jako absolutní cestu k souboru .svg. Pro jednu ikonu zvol vždy jen jednu z těchto možností: vložený obsah se hodí pro jednu či dvě ikony, souborová cesta se lépe udržuje u rozsáhlejší knihovny.
1. Připrav plugin a nejdřív zaregistruj sbírku
Ikonu nemůžeš registrovat dřív než její sbírku. Pokud pořadí obrátíš, ikona se v pickeru tiše neukáže. Vytvoř proto ve wp-content/plugins/ tuto strukturu:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgDo hlavního souboru pluginu vlož hlavičku, ochranu proti přímému spuštění, konstantu s cestou a registraci sbírky. Hook init tu běží s výchozí prioritou 10.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registers 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' ),
)
);
}Název myplugin se stane prefixem všech ikon, například myplugin/heart a myplugin/star. Hodnota label se zobrazí jako nadpis sekce ve výběru ikon. Plugin aktivuj v nabídce „Pluginy → Instalované pluginy“; samotná prázdná sbírka se zatím nikde nevykreslí.
2. Přidej SVG přímo i ze souborů
Vložená ikona přes content
Pro malý počet ikon můžeš SVG zapsat přímo do PHP. Následující funkce registruje srdce na prioritě 20, takže se spustí až po vytvoření sbírky.
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>',
)
);
}Jméno myplugin/heart dodržuje formát sbirka/slug. label popisuje ikonu v pickeru a content obsahuje její SVG. Atribut stroke="currentColor" zajistí, že tah převezme barvu okolního textu, místo aby v SVG zůstala napevno zadaná barva.
Ikony ze souborů přes file_path
Hvězdu a záložku ulož do složky icons/. U ikon na disku WordPress načte soubor podle potřeby.
<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',
)
);
}Oproti vloženému SVG se mění jen content na file_path; obě ikony zůstávají ve stejné sbírce. Po otevření bloku core/icon se ve výběru objeví sekce „MyPlugin“ s ikonami Heart, Star a Bookmark. Když některá chybí, zkontroluj nejprve pořadí registrace: sbírka musí běžet na výchozí prioritě a ikony až poté, například na prioritě 20.
core/icon. — Forrás: WPVibes.com3. Načti automaticky celou složku ikon
Volat wp_register_icon() ručně pro desítky ikon nedává smysl. Místo předchozí funkce myplugin_register_file_icons() použij hromadnou registraci: každý soubor .svg ve složce se načte při dalším requestu a dostane jméno podle názvu souboru.
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' ) vrátí všechny SVG soubory ve složce. basename( $file_path, '.svg' ) odstraní cestu i příponu, takže z advanced-button.svg vznikne advanced-button; výraz ucwords( str_replace( '-', ' ', $slug ) ) pak vytvoří popisek „Advanced Button“ pro picker. Smyčka každou položku přidá do sbírky myplugin/.
Nové SVG stačí vložit do složky icons/ a obnovit editor, žádnou další registraci už nepíšeš. Tento vzor funguje pro několik ikon i pro stovky; vložené srdce může zůstat registrované samostatně, zatímco soubory se načítají hromadně.
4. Použij ikony v editoru, PHP a blocích
Blok core/icon a REST API
Blok core/icon automaticky načte všechny zaregistrované sbírky. Autor obsahu vloží blok, vybere ikonu a WordPress ji vykreslí i na frontendu bez dalšího kódu. Stejná data poskytují endpointy /wp-json/wp/v2/icons pro ikony a /wp-json/wp/v2/icon-collections pro sbírky, takže je mohou číst i externí nástroje.
Vykreslení v PHP pomocí wp_get_icon()
wp_get_icon() vrací SVG jako řetězec. Můžeš jej rovnou vypsat nebo vložit do vlastního HTML.
echo wp_get_icon( 'myplugin/heart' );Druhý argument dovolí řídit rozměr, CSS třídu a přístupný popisek. size nastaví SVG atributy width a height v pixelech, class přidá třídu SVG elementu a label vytvoří aria-label pro čtečky obrazovky. Pole argumentů podporuje také title.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);Shortcode pro obsah
Následující shortcode [myplugin_icon] umožní vložit zaregistrovanou ikonu do příspěvku, stránky i widgetu. Sanitizuje název, velikost i CSS třídu; pokud ikona neexistuje, nevrátí nic.
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 se vykreslí vedle textu a atribut size určí její rozměr. Díky currentColor automaticky převezme barvu okolního textu.
Ikona vlastního bloku
Registrovaná ikona může nahradit Dashicon při registraci bloku. Místo vestavěného názvu předáš do klíče icon celé jméno vlastní ikony; funguje to pro bloky registrované JavaScriptem i pro bloky, které registruješ pouze přes PHP.
'icon' => 'warning', // Dashicon
'icon' => 'myplugin/star', // Zaregistrovaná vlastní SVG ikonaVkladač bloků pak zobrazí vlastní SVG namísto obecného Dashiconu. Jeden zápis do registru tak obslouží editor, PHP šablony i REST vrstvu.
5. Nastyluj SVG tak, aby zapadlo do rozhraní
Nejdůležitější pravidlo pro přizpůsobivé SVG zní: používej stroke="currentColor", případně fill="currentColor", a ne pevně zadané barvy. Ikona pak funguje jako text – v červeném textu bude červená, v tmavé šabloně tmavá a v odkazu převezme jeho barvu.
<!-- Nevhodné: ikona zůstane vždy červená -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Pevnou barvu použij jen tam, kde ji ikona opravdu vyžaduje, například u značky nebo stavového indikátoru. Protože SVG používá currentColor, nastavíš cílovou barvu přes CSS třídu předanou ve funkci wp_get_icon():
.featured-icon {
color: #f59e0b; /* Jantarová bez ohledu na okolní text */
}Pro ikony ze shortcodu nebo z wp_get_icon() řeší přesnou jednorázovou velikost argument size. Pokud chceš řídit velikost přes CSS nebo přidat reakci na hover, styluj obalový element či SVG:
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}sizevwp_get_icon()použij pro jednorázový případ s konkrétním rozměrem, kde se nevyplatí psát CSS.- CSS třídy, předané argumentem
classnebo přidané na obalový element, použij pro ikony na více místech, pro jednotný vzhled a pro styly závislé na stavu – hover, focus či active – nebo kontextu, například uvnitř odkazu a nadpisu. - U shortcodu upravíš jednotlivý případ atributem
size; konzistentní vzhled napříč webem nastavíš pravidlem pro.myplugin-icon-inline svg.
6. Odeber ikonu nebo celou sbírku
Pro odstranění jediné ikony, například během vývoje nebo když ji nová verze pluginu přestane poskytovat, zavolej wp_unregister_icon(). Ve výběru zmizí při dalším requestu; již uložené příspěvky s touto ikonou v bloku core/icon se ale začnou vykreslovat prázdné, protože WordPress obsah příspěvků nepřepisuje.
wp_unregister_icon( 'myplugin/bookmark' );Při deaktivaci pluginu odstraň celou sbírku pomocí wp_unregister_icon_collection(). Není nutné procházet jednotlivé ikony: odstranění sbírky uklidí všechny její položky najednou.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Na co si dát pozor
- Sbírku zaregistruj vždy před ikonami. Nejjednodušší je nechat sbírku na výchozí prioritě hooku
inita ikonám nastavit vyšší prioritu, například 20. - V jedné sbírce můžeš kombinovat
contentafile_path; každé voláníwp_register_icon()funguje nezávisle. - Dvě sbírky mohou mít ikonu se stejným slugem.
myplugin/heartaotherplugin/heartse nebijí, protože jedinečnost určuje celé jméno včetně prefixu sbírky. - WordPress při registraci SVG neupravuje ani nesanitizuje. Dodaný řetězec nebo obsah souboru odešle tak, jak jej poskytneš. Před nasazením proto odstraň skripty, externí reference a vše zbytečné.
- Z SVG odstraň pevné hodnoty
fillastroke, atributywidthaheightna kořenovém elementu<svg>, bloky<style>i skripty. PonechviewBoxa strukturní atributy; pro barvy používejcurrentColor. - Ikony můžeš registrovat i v
functions.phpšablony a pro cestu k souborům použítget_stylesheet_directory(). Po změně šablony však takto zaregistrované ikony zmizí.
Shrnutí
API vlastních ikon ve WordPressu 7.1 propojí editor, PHP a REST API přes jeden registr. Založ sbírku, vyber mezi vloženým SVG a soubory na disku, u větší sady přejdi na glob() a SVG připrav s currentColor a bezpečným obsahem.
Pokud plugin poskytuje vlastní bloky, předej zaregistrované jméno i do register_block_type() jako hodnotu icon. Získáš značkovou podobu vkladače bloků bez JavaScriptového build kroku a stejnou ikonu následně použiješ v šablonách, obsahu i nástrojích napojených na REST API.
Kompletní ukázkový plugin se vzorovými SVG soubory, README a hromadnou registrací najdeš v repozitáři níže.
Kompletní ukázkový plugin pro vlastní SVG ikonyReference / Zdroje
Tereza Novotná
Šéfredaktorka českého týmu, agile koučka a scrum master. Vedení týmů a optimalizace vývojových procesů je mou specializací.
Všechny příspěvky
