Eigen SVG-iconen registreren in WordPress 7.1
Eigen SVG-iconen in de blok-editor vereisten jarenlang JavaScript, een buildstap of een kwetsbare omweg. WordPress 7.1 introduceert een publieke API waarmee je iconen vanuit een plugin registreert, zonder JavaScript-buildproces. Dezelfde registratie voedt de core/icon-kiezer, PHP-templates en de REST API.
WordPress 7.1 verschijnt op 19 augustus 2026. De API werkt tijdens ontwikkeling ook met WordPress 7.1 RC; controleer je implementatie na de definitieve release nogmaals tegen de uiteindelijke build.
Wat je bouwt
Je maakt een kleine plugin met een iconencollectie, drie SVG-iconen en een patroon dat automatisch alle SVG-bestanden uit een map registreert. Daarna gebruik je die iconen in de editor, in PHP, via een shortcode en als blokicoon.
- Een plugin
mypluginmet een geregistreerde collectiemyplugin. - Drie inzetbare iconen: een inline geregistreerd hart en een ster en bladwijzer uit
.svg-bestanden. - Een bulkpatroon dat elk SVG-bestand uit een map automatisch registreert.
- Een shortcode waarmee redacteuren een geregistreerd icoon in berichten, pagina’s en widgets plaatsen.
- Een custom blokicoon voor
register_block_type(), ook bruikbaar voor JavaScript-geregistreerde en PHP-only blokken.
Wat je vooraf nodig hebt
- WordPress 7.1 of hoger; WordPress 7.1 RC volstaat voor ontwikkeling.
- Een paar SVG-iconen, of de voorbeelden uit deze handleiding.
- Een lokale ontwikkelomgeving, zoals LocalWP, WordPress Studio of
wp-env. - Basiskennis van PHP.
De iconen-API in drie minuten
De API bestaat uit drie functies en het concept van collecties. Een collectie is een benoemde groep iconen. Elk icoon hoort bij precies zo’n collectie, die als namespace optreedt en conflicten met de WordPress-core of andere plugins voorkomt.
wp_register_icon_collection( $name, $args )registreert een benoemde iconencollectie.wp_register_icon( $name, $args )registreert één icoon.wp_get_icon( $name, $args )rendert een icoon in PHP en geeft de SVG als string terug.
De collectienaam vormt het voorvoegsel van elk icoon. Daardoor zijn core/plus en myplugin/plus twee verschillende iconen. Geef de SVG per icoon op met óf content, een SVG-string direct in PHP, óf file_path, een absoluut pad naar een .svg-bestand. Combineer die twee opties niet voor één icoon: content past bij een of twee iconen, terwijl file_path beter schaalt voor een volledige map.
1. Maak de plugin en registreer eerst de collectie
Registreer de collectie vóór je een icoon toevoegt. Als je een icoon aan een nog niet bestaande collectie koppelt, verschijnt het stilzwijgend niet in de kiezer. Maak in wp-content/plugins/ de volgende mapstructuur.
myplugin/
├── myplugin.php
└── icons/
├── star.svg
└── bookmark.svgMaak vervolgens myplugin.php. De init-hook gebruikt standaard prioriteit 10; de iconen registreren we straks met prioriteit 20, zodat de collectie al bestaat.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registreert eigen SVG-iconen voor 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' ),
)
);
}De naam myplugin wordt het voorvoegsel voor namen als myplugin/heart en myplugin/star. Het label vormt de sectiekop in de iconenkiezer. Activeer de plugin via Plugins → Geïnstalleerde plugins; zonder geregistreerde iconen toont de collectie nog niets.
2. Registreer iconen inline en vanuit bestanden
WordPress ondersteunt beide registratievormen naast elkaar in één collectie. Registreer het hart inline als je geen extra bestand nodig hebt.
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>',
)
);
}De naam volgt het patroon collectie/icoonslug. label verschijnt in de kiezer en content bevat de markup. Het attribuut stroke="currentColor" laat het icoon de kleur van de omringende tekst overnemen, zonder vaste vulkleur.
Sla voor iconen op schijf deze bestanden op in de map icons/. Gebruik vervolgens file_path; WordPress leest het bestand wanneer dat nodig is.
<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',
)
);
}Open nu het core/icon-blok in de editor. De kiezer bevat een sectie MyPlugin met Heart, Star en Bookmark. Ontbreekt een icoon, controleer dan eerst de hookprioriteiten: registreer de collectie op de standaardprioriteit en de iconen erna, bijvoorbeeld op prioriteit 20.
3. Registreer een hele map met SVG-bestanden
Losse aanroepen naar wp_register_icon() zijn niet praktisch voor een grote iconenbibliotheek. Vervang de functie voor losse bestandsiconen door deze bulkvariant: PHP zoekt alle SVG-bestanden en registreert ze bij de volgende request automatisch.
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' )retourneert elk.svg-bestand uit de map.basename( $file_path, '.svg' )haalt de bestandsnaam zonder extensie op.advanced-button.svgwordt dusadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )maakt daarvan een leesbaar label voor de kiezer:advanced-buttonwordtAdvanced Button.- De lus registreert ieder icoon onder de collectie
myplugin/.
Plaats een nieuw SVG-bestand in icons/ en vernieuw de editor: het icoon verschijnt zonder codewijziging in de kiezer. Dit patroon schaalt van drie naar honderden iconen; het inline hart blijft apart geregistreerd en de map bevat de ster, bladwijzer en alle later toegevoegde bestanden.
4. Gebruik dezelfde iconen op drie plekken
In het core/icon-blok en via REST
De kiezer van het core/icon-blok toont automatisch elke geregistreerde collectie. Gebruikers kiezen een MyPlugin-icoon en WordPress rendert het op de frontend; daarvoor schrijf je geen extra code. Externe tools die WordPress-data lezen, krijgen de iconen ook via /wp-json/wp/v2/icons en de collecties via /wp-json/wp/v2/icon-collections.
In PHP met wp_get_icon()
wp_get_icon() geeft de SVG als string terug. Echo het resultaat direct voor de eenvoudigste toepassing.
echo wp_get_icon( 'myplugin/heart' );Geef voor templates een tweede argument mee om de afmetingen, CSS-klasse en toegankelijkheid te bepalen.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Uitgelicht', 'myplugin-icons' ),
)
);sizesteltwidthenheightvan de SVG in pixels in.classvoegt een CSS-klasse toe aan het SVG-element.labelzetaria-labelvoor schermlezers.
Maak desgewenst een shortcode voor berichtinhoud. Deze variant saneert de icoonnaam, maat en CSS-klasse, en retourneert niets als het gevraagde icoon niet bestaat.
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="Hallo wereld"]
[myplugin_icon name="star" text="Uitgelicht bericht" size="32"]
[myplugin_icon name="bookmark" text="Bewaar voor later" size="20"]Het icoon staat naast de tekst en volgt de maat uit het attribuut size. Door currentColor neemt de SVG automatisch de kleur van de omringende tekst over.
Als icoon van een custom blok
Je kunt een standaard-Dashicon in register_block_type() vervangen door de volledige naam van een geregistreerd icoon. De blokinserter toont dan je eigen SVG, zowel bij JavaScript-geregistreerde blokken als PHP-only blokken.
'icon' => 'warning', // Gebruikt een Dashicon'icon' => 'myplugin/star', // Gebruikt een geregistreerd eigen icoonDit sluit aan op een PHP-only blokarchitectuur: je registreert je blok en zijn icoon zonder buildstap. De iconenregistratie fungeert daarbij als één bron voor de editor, PHP en REST.
5. Geef SVG-iconen met CSS een native uitstraling
Een SVG die zich aanpast aan kleur, lettergrootte en interactie voelt in elk thema meer geïntegreerd. De class uit wp_get_icon() biedt een CSS-hook voor templates; in de blok-editor ontbreekt dat argument, dus gebruik daar ook classes op omliggende elementen wanneer nodig.
Gebruik currentColor voor overerving
Gebruik in SVG’s stroke="currentColor" of fill="currentColor" in plaats van vaste kleuren. Een icoon in rode tekst wordt dan rood, in een donker thema donker en in een link krijgt het de linkkleur. Het gedraagt zich daarmee als tekst.
<!-- Vermijd een vaste kleur: dit icoon blijft altijd rood. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Laat vaste kleuren weg in de SVG-bestanden van je bibliotheek. Zo passen de iconen in ieder thema, in plaats van met een deel van de thema’s te botsen.
Forceer alleen waar nodig een specifieke kleur
Een merkmarkering of statusindicator moet soms ongeacht de context dezelfde kleur krijgen. Zet in dat geval color op de SVG via de class die je aan wp_get_icon() doorgaf. Omdat de SVG currentColor gebruikt, neemt de stroke of fill die waarde over.
.featured-icon {
color: #f59e0b; /* Amber, ongeacht de omringende tekstkleur. */
}Pas maat en hoverstatus aan
Bij iconen uit de shortcode of wp_get_icon() regelt size de pixelmaat direct. Gebruik CSS als je de maat centraal beheert of interactiestatussen zoals hover, focus en actief nodig hebt.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Gebruik
sizeinwp_get_icon()voor eenmalige gevallen waarin een exacte pixelmaat telt en CSS geen voordeel biedt. - Gebruik CSS-classes, via het argument
classof via een wrapper, wanneer iconen op veel plekken dezelfde stijl nodig hebben of wanneer de stijl afhangt van status of context, zoals een link of kop. - Gebruik bij de shortcode
sizevoor kleine afwijkingen per toepassing en CSS op.myplugin-icon-inline svgvoor consistente styling op de hele site.
6. Verwijder iconen en collecties
WordPress 7.1 bevat ook functies om één icoon of een hele collectie weer uit te schrijven. Dat is nuttig tijdens ontwikkeling en wanneer een pluginupdate een icoon laat vervallen.
wp_unregister_icon( 'myplugin/bookmark' );Het icoon verdwijnt bij de volgende request uit de kiezer. Bestaande berichten met dit icoon in een core/icon-blok blijven hun inhoud houden, maar renderen vervolgens leeg; WordPress herschrijft die berichtinhoud niet.
Schoon bij het deactiveren van je plugin de hele collectie op. Eén aanroep verwijdert alle iconen die erin zitten; je hoeft niet over de individuele iconen te lopen.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Belangrijke aandachtspunten
De API volgt een register-once-use-everywhere-patroon: de core/icon-blok kiest uit hetzelfde register dat wp_get_icon() in PHP gebruikt, terwijl de REST API die gegevens beschikbaar maakt voor externe tools, waaronder AI-agents. Dit sluit aan bij andere fundamentele API’s in WordPress, zoals Abilities API en block bindings.
- Registreer altijd eerst de collectie en daarna de iconen.
- Kies per icoon
contentvoor inline SVG offile_pathvoor een bestand op schijf; beide vormen mogen in dezelfde collectie staan. - Gebruik
glob()voor een map met veel iconen in plaats van tientallen losse registraties. - Gebruik
wp_get_icon( $name, $args )metsize,classenlabelvoor templategebruik. - Ontwerp SVG’s met
currentColor, zodat ze zich aan hun omgeving aanpassen. - Sanitiseer SVG’s zelf voor je ze verspreidt. WordPress wijzigt de SVG niet tijdens registratie: de exacte string of bestandsinhoud die je opgeeft, wordt geserveerd. Verwijder scripts, externe verwijzingen en overbodige inhoud.
De complete voorbeeldplugin, inclusief SVG-voorbeelden, README en bulkregistratiepatroon, staat op GitHub. Werk je SVG’s bij door vaste fill– en stroke-kleuren, width– en height-attributen op het root-<svg> en alle <style>-blokken of scripts te verwijderen. Behoud viewBox en structurele attributen, en gebruik currentColor waar een kleur nodig is.
Veelgestelde vragen
Moet ik een collectie registreren voordat ik iconen registreer?
Ja. Iconen moeten bij een bestaande collectie horen, anders verschijnen ze stilzwijgend niet in de kiezer. Registreer de collectie op init met de standaardprioriteit en registreer de iconen daarna met een hogere prioriteit, zoals 20.
Mag ik inline content-iconen en file_path-iconen in dezelfde collectie combineren?
Ja. Elke aanroep van wp_register_icon() staat op zichzelf. Gebruik content voor een of twee iconen en file_path voor de rest; WordPress behandelt ze na registratie hetzelfde.
Werken eigen iconen als blokicoon in register_block_type()?
Ja. Geef de geregistreerde naam, bijvoorbeeld 'myplugin/star', door aan de sleutel icon in register_block_type(). De blokinserter toont dan de eigen SVG in plaats van een Dashicon. Dit werkt voor JavaScript-geregistreerde blokken én PHP-only blokken.
Geeft wp_get_icon() HTML of een string terug?
wp_get_icon() retourneert de SVG als string. Echo die direct of verpak hem in eigen HTML. De tweede array $args accepteert size, class, label voor aria-label en title.
Kan ik iconen vanuit een thema registreren in plaats van vanuit een plugin?
Ja. Gebruik dezelfde aanroep naar wp_register_icon() in functions.php van je thema en gebruik get_stylesheet_directory() voor het bestandspad. Houd rekening met de keerzijde: de iconen verdwijnen zodra iemand van thema wisselt.
Wat gebeurt er wanneer twee collecties dezelfde icoonnaam gebruiken?
Collecties vormen namespaces. myplugin/heart en anderplugin/heart kunnen daardoor naast elkaar bestaan zonder conflict. De volledige naam, inclusief het collectievoorvoegsel, maakt elk icoon uniek.
Referenties / Bronnen
Sophie de Vries
Hoofdredacteur van het Nederlandse team, evangelist voor toegankelijkheid en webstandaarden. Ik geloof in het open web en inclusief design. WCAG-expert.
Alle berichten
