Eigene SVG-Icons in WordPress 7.1 registrieren
Eigene SVG-Icons im Block-Editor einzubinden, erforderte lange JavaScript, einen Build-Schritt oder unzuverlässige Behelfslösungen. WordPress 7.1 führt dafür eine öffentliche API ein: Du registrierst Icons in einem Plugin und verwendest sie im core/icon-Block, in PHP und über die REST-API – ohne JavaScript-Build-Schritt.
WordPress 7.1 soll am 19. August 2026 erscheinen. Für die Entwicklung funktioniert auch der Release Candidate von WordPress 7.1. In dieser Anleitung baust du ein kleines Plugin mit einer Icon-Collection, drei Beispiel-Icons, einer automatischen Registrierung für einen ganzen Ordner und einem Shortcode.
Das Plugin und seine Voraussetzungen
Am Ende enthält dein Plugin die Collection myplugin, ein inline registriertes Herz sowie Stern und Lesezeichen aus SVG-Dateien. Außerdem kannst du jedes SVG in einem Ordner automatisch registrieren, Icons im Inhalt per Shortcode ausgeben und ein Icon als Symbol eines eigenen Blocks einsetzen.
Du brauchst dafür WordPress 7.1 oder neuer, einige SVG-Dateien, eine lokale Entwicklungsumgebung wie LocalWP, WordPress Studio oder wp-env sowie grundlegende PHP-Kenntnisse. Das vollständige Beispiel-Plugin mit SVG-Dateien, README und der Registrierung für ganze Ordner steht auf GitHub.
Die API: Collections registrieren, Icons ausgeben
Die API besteht aus drei Funktionen und Collections als Ordnungsprinzip. Eine Collection ist eine benannte Gruppe von Icons. Jedes Icon muss zu genau einer Collection gehören; deren Name bildet den Präfix des vollständigen Icon-Namens. Dadurch kollidieren etwa core/plus und myplugin/plus nicht miteinander.
Die drei Funktionen
wp_register_icon_collection( $name, $args ) registriert eine Collection. Mit wp_register_icon( $name, $args ) legst du ein einzelnes Icon an. wp_get_icon( $name, $args ) rendert ein Icon in PHP und gibt dessen SVG als String zurück.
Beim Registrieren eines Icons übergibst du das SVG auf eine von zwei Arten: content enthält den SVG-Markup direkt als String in PHP, file_path verweist auf den absoluten Pfad einer .svg-Datei. Verwende pro Icon nur eine dieser Varianten. content eignet sich für ein oder zwei Icons, file_path skaliert besser für umfangreiche Icon-Bibliotheken in einem Ordner.
1. Plugin anlegen und Collection zuerst registrieren
Lege im Verzeichnis wp-content/plugins/ folgende Struktur an. Die Collection muss bereits existieren, bevor du ihr Icons hinzufügst. Registrierst du ein Icon vorher, erscheint es nicht im Picker, ohne dass WordPress einen sichtbaren Fehler ausgibt.
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgErstelle anschließend die Plugin-Datei. Die Action für die Collection nutzt die Standard-Priorität 10 auf init. Der Name myplugin wird später zum Präfix aller enthaltenen Icons, etwa myplugin/heart oder myplugin/star. Das Label erscheint als Überschrift des jeweiligen Bereichs im Icon-Picker.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registriert eigene SVG-Icons für 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__ ) );
/**
* Zuerst die Icon-Collection registrieren.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Aktiviere das Plugin unter Plugins → Installierte Plugins. Eine leere Collection rendert noch nichts; erst registrierte Icons machen sie im Picker sichtbar.
2. Icons inline und aus Dateien registrieren
WordPress unterstützt beide Eingabeformen auch innerhalb derselben Collection. Das Herz bleibt im PHP-Code, während Stern und Lesezeichen aus Dateien im Ordner icons/ kommen.
Herz mit inline-SVG über content anlegen
Hänge diese Funktion mit Priorität 20 an init. Sie läuft damit nach der Collection-Registrierung. Der Name folgt dem Muster collection/icon-slug, das Label beschreibt das Icon im Picker und content enthält den SVG-Markup. stroke="currentColor" sorgt dafür, dass das Icon die Textfarbe seiner Umgebung übernimmt, statt eine feste Füllfarbe zu erzwingen.
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>',
)
);
}Stern und Lesezeichen per file_path laden
Speichere zunächst diese Dateien im Unterordner icons/. Bei der dateibasierten Variante liest WordPress die jeweilige SVG-Datei bei Bedarf ein.
<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',
)
);
}Öffne jetzt einen core/icon-Block im Editor. Der Picker zeigt die neue Collection MyPlugin mit Heart, Star und Bookmark. Falls ein Icon fehlt, prüfe zuerst die Reihenfolge: Die Collection muss mit Standard-Priorität registriert werden, die Icons danach, beispielsweise mit Priorität 20.
3. Alle SVG-Dateien eines Ordners automatisch registrieren
Bei einer echten Icon-Bibliothek sind einzelne Aufrufe von wp_register_icon() nicht wartbar. Ersetze die Funktion myplugin_register_file_icons() durch diese Variante. Sie findet bei jedem Request sämtliche SVG-Dateien im Ordner und registriert sie 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' ) liefert alle .svg-Dateien im Zielordner. basename( $file_path, '.svg' ) entfernt Pfad und Erweiterung, aus advanced-button.svg wird also advanced-button. ucwords( str_replace( '-', ' ', $slug ) ) erzeugt daraus das lesbare Picker-Label „Advanced Button“. Die Schleife registriert jedes Ergebnis unter myplugin/.
Lege neue SVG-Dateien in icons/ ab und aktualisiere den Editor. Sie erscheinen ohne weitere Code-Änderung im Picker. Das Muster skaliert von drei Icons auf Hunderte: Das Herz registrierst du weiterhin inline, Stern, Lesezeichen und alle zusätzlich abgelegten Dateien kommen aus dem Ordner.
4. Icons im Editor, in PHP und über REST verwenden
Eine Registrierung versorgt drei Nutzungskontexte. Der core/icon-Block liest jede registrierte Collection automatisch aus. Externe Tools können Icons über /wp-json/wp/v2/icons abfragen; für Collections gibt es zusätzlich /wp-json/wp/v2/icon-collections.
SVG in PHP mit wp_get_icon() ausgeben
wp_get_icon() liefert das SVG als String zurück. Du kannst es direkt ausgeben oder in eigenen HTML-Markup einbetten.
echo wp_get_icon( 'myplugin/heart' );Für Templates steuerst du Pixelgröße, CSS-Klasse und Barrierefreiheit über das zweite Argument. size setzt width und height des SVG in Pixeln, class ergänzt eine CSS-Klasse am SVG-Element und label setzt aria-label für Screenreader.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);Icons per Shortcode in Beiträge und Seiten einfügen
Mit dem Shortcode [myplugin_icon] können Redakteure ein registriertes Icon in Beiträgen, Seiten oder Widgets verwenden. Die Funktion bereinigt den Icon-Namen, die Größe und die Klasse. Liefert wp_get_icon() kein Icon, gibt der Shortcode einen leeren String zurück.
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"]Das Icon steht jeweils neben dem Text und übernimmt die über size angegebene Größe. Wegen currentColor passt es sich automatisch an die umgebende Textfarbe an.
Eigenes Icon für einen Block registrieren
Du kannst ein registriertes Icon auch als Block-Symbol an register_block_type() übergeben. Statt eines Dashicons wie warning trägst du den vollständigen Namen des Custom Icons ein. Der Block-Inserter zeigt dann das eigene SVG; das funktioniert bei JavaScript-registrierten und bei reinen PHP-Blöcken.
'icon' => 'warning', // Verwendet ein Dashicon'icon' => 'myplugin/star', // Verwendet ein registriertes eigenes Icon5. SVG-Icons mit CSS anpassen
Gut integrierte Icons übernehmen die Textfarbe, skalieren passend zur Umgebung und können auf Interaktionen reagieren. Die über wp_get_icon() gesetzte class liefert dafür einen CSS-Hook. Im Block-Editor steht dieses Argument nicht zur Verfügung; die folgenden SVG- und CSS-Muster funktionieren jedoch überall, wo das Icon erscheint.
currentColor statt fester Farben verwenden
Nutze im SVG stroke="currentColor" oder fill="currentColor", nicht fest codierte Farben. So verhält sich das SVG wie Text: In rotem Text wird es rot, in einem dunklen Theme dunkel und in einem Link übernimmt es die Linkfarbe.
<!-- Nicht verwenden: Das Icon bleibt immer rot. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>SVGs ohne feste Farben passen zu jedem Theme deutlich besser. Wenn ein Marken- oder Status-Icon trotzdem zwingend eine Farbe braucht, setzt du diese über CSS auf dem SVG. Da das Icon currentColor nutzt, wandert der Wert in stroke oder fill weiter.
.featured-icon {
color: #f59e0b; /* Amber, unabhängig von der Textfarbe */
}Größe und Hover-Zustände steuern
Für ein einzelnes Icon setzt du die exakte Pixelgröße direkt mit size in wp_get_icon(). Sollen mehrere Icons konsistent aussehen oder auf Hover, Focus, Active und ihren Kontext reagieren, nutze CSS-Klassen am SVG oder an einem umschließenden Element.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}Im Shortcode-Beispiel eignen sich size-Attribute für kleine Einzelfall-Anpassungen. Für ein einheitliches Erscheinungsbild auf der gesamten Website setzt du Regeln auf .myplugin-icon-inline svg.
6. Icons und Collections wieder entfernen
WordPress 7.1 stellt passende Funktionen bereit, um einzelne Icons oder eine komplette Collection zu entfernen. Das ist während der Entwicklung nützlich oder wenn ein Plugin-Update ein Icon aus dem Sortiment nimmt.
Ein einzelnes Icon entfernen
wp_unregister_icon( 'myplugin/bookmark' );Beim nächsten Request verschwindet das Icon aus dem Picker. Bereits gespeicherte core/icon-Blöcke, die dieses Icon enthalten, rendert WordPress dann leer; der Inhalt bestehender Beiträge wird nicht umgeschrieben.
Beim Deaktivieren die ganze Collection entfernen
Deaktivierst du das Plugin, sollten seine Icons nicht mehr im Picker auftauchen. wp_unregister_icon_collection() entfernt alle enthaltenen Icons in einem Aufruf; du musst nicht über jedes einzelne Icon iterieren.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Häufige Fragen zur Custom-Icons-API
Muss die Collection vor den Icons registriert werden?
Ja. Icons benötigen eine vorhandene Collection, sonst erscheinen sie nicht im Picker. Registriere die Collection auf init mit der Standard-Priorität und die Icons danach, etwa mit Priorität 20.
Darf eine Collection content– und file_path-Icons mischen?
Ja. Jeder Aufruf von wp_register_icon() ist unabhängig. Verwende content für ein oder zwei Icons und file_path für die übrigen. Nach der Registrierung behandelt WordPress beide Varianten gleich.
Funktionieren Custom Icons als Block-Icons in register_block_type()?
Ja. Übergib dem Schlüssel icon den registrierten Namen wie 'myplugin/star'. Der Block-Inserter zeigt dann das eigene SVG statt eines Dashicons – sowohl für JavaScript-registrierte als auch für reine PHP-Blöcke.
Liefert wp_get_icon() HTML oder einen String?
Die Funktion gibt das SVG als String zurück. Du kannst den Wert direkt mit echo ausgeben oder in eigenen HTML-Markup einschließen. Das zweite Array $args akzeptiert size, class, label für aria-label und title.
Welche SVG-Attribute solltest du vor der Registrierung entfernen?
Entferne fest codierte fill– und stroke-Farben, width und height am root-<svg> sowie alle <style>-Blöcke und Scripts. Behalte viewBox und strukturelle Attribute. Verwende currentColor für Farbangaben.
Kannst du Icons in einem Theme statt in einem Plugin registrieren?
Ja. Derselbe Aufruf von wp_register_icon() funktioniert in der functions.php eines Themes; für den Dateipfad verwendest du get_stylesheet_directory(). Beachte jedoch den Nachteil: Wechselst du das Theme, verschwinden auch dessen registrierte Icons.
Was passiert bei gleichem Icon-Namen in zwei Collections?
Collections bilden Namespaces. myplugin/heart und anotherplugin/heart können deshalb ohne Konflikt nebeneinander existieren. Erst der vollständige Name inklusive Collection-Präfix ist eindeutig.
Bereinigt WordPress SVGs bei der Registrierung?
Nein. WordPress verändert beim Registrieren weder den String in content noch den Inhalt einer Datei aus file_path. Bereinige SVGs vor dem Ausliefern selbst und entferne Scripts, externe Referenzen sowie alles Unnötige.
Nächste Schritte
Registriere zuerst deine Collection, wähle anschließend pro Icon content oder file_path und verwende für größere Sammlungen die glob()-Variante. Setze in deinen SVGs currentColor, damit sie sich in Themes, Links und Textfarben einfügen. Danach kannst du dieselbe Registrierung ohne zusätzlichen Build-Schritt im Editor, in PHP-Templates, über REST und als Block-Symbol nutzen.
Referenzen / Quellen
Amara Schmidt
Full-Stack-Entwicklerin, Spezialistin für TypeScript und moderne Web-Frameworks. Next.js und serverlose Architekturen interessieren mich am meisten. Offen für neue Technologien.
Alle Beiträge
