Własne ikony SVG w WordPressie 7.1 – kompletny przewodnik

Własne ikony SVG w edytorze blokowym dotąd zwykle wymagały JavaScriptu, procesu budowania albo kruchego obejścia problemu. WordPress 7.1 wprowadza publiczne API, które pozwala zarejestrować ikonę w PHP, wyświetlić ją w bloku core/icon, wyrenderować w szablonie i udostępnić przez REST API – bez kroku build.

W tym przewodniku zbudujesz małą wtyczkę z kolekcją ikon, dodasz SVG zapisane w kodzie oraz w plikach, zautomatyzujesz rejestrację całego katalogu i użyjesz ikon w treści, szablonach oraz blokach. WordPress 7.1 ma ukazać się 19 sierpnia 2026 roku; przykłady odpowiadają kodowi planowanemu na dzień wydania.

Co zbudujesz i czego potrzebujesz

Przykładowa wtyczka myplugin-custom-icons utworzy kolekcję myplugin. Zarejestrujesz trzy ikony gotowe do użycia: serce jako SVG zapisany bezpośrednio w PHP, a gwiazdkę i zakładkę z plików .svg.

Poznasz też wzorzec masowej rejestracji, który odczytuje każdy plik SVG z katalogu, shortcode wstawiający dowolną zarejestrowaną ikonę do treści oraz użycie własnej ikony jako ikony bloku. Ten sam mechanizm działa również z blokami rejestrowanymi wyłącznie w PHP.

Przed rozpoczęciem przygotuj następujące elementy:

WordPress 7.1 lub nowszy; do prac deweloperskich wystarczy WordPress 7.1 RC.
Kilka plików ikon SVG albo pliki z przykładów poniżej.
Lokalne środowisko deweloperskie, na przykład LocalWP, WordPress Studio lub wp-env.
Podstawową znajomość PHP.

Poznaj API ikon

API własnych ikon opiera się na trzech funkcjach i kolekcjach. Kolekcja to nazwany zbiór ikon, a każda ikona musi do niego należeć.

wp_register_icon_collection( $name, $args ) rejestruje nazwaną grupę ikon.
wp_register_icon( $name, $args ) rejestruje pojedynczą ikonę.
wp_get_icon( $name, $args ) renderuje SVG w PHP i zwraca je jako string.

Nazwa kolekcji tworzy prefiks nazw ikon. Dzięki temu core/plus i myplugin/plus nie kolidują ze sobą, podobnie jak ikony pochodzące z różnych wtyczek. Pełna nazwa, razem z prefiksem kolekcji, jest unikalnym identyfikatorem.

Przy rejestracji podaj SVG na jeden z dwóch sposobów. Argument content przyjmuje kod SVG jako string osadzony w PHP, natomiast file_path wymaga bezwzględnej ścieżki do pliku .svg na dysku. Dla pojedynczej ikony wygodny jest content; przy większym katalogu lepiej sprawdza się file_path. Nie podawaj obu argumentów dla tej samej ikony.

1. Utwórz wtyczkę i najpierw zarejestruj kolekcję

Kolekcję trzeba zarejestrować, zanim dodasz do niej pierwszą ikonę. Gdy odwrócisz tę kolejność, ikona nie pojawi się w selektorze i WordPress nie zgłosi błędu.

W katalogu wp-content/plugins/ utwórz taką strukturę:

myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
    ├── star.svg
    └── bookmark.svg

myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
    ├── star.svg
    └── bookmark.svg

Następnie utwórz plik główny wtyczki. Nazwa kolekcji myplugin stanie się prefiksem nazw myplugin/heart, myplugin/star i kolejnych ikon, a wartość label zobaczysz jako nagłówek sekcji w selektorze.

<?php
/**
 * Plugin Name: MyPlugin Custom Icons
 * Description: Rejestruje własne ikony SVG dla WordPressa 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' ),
        )
    );
}

<?php
/**
 * Plugin Name: MyPlugin Custom Icons
 * Description: Rejestruje własne ikony SVG dla WordPressa 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' ),
        )
    );
}

Aktywuj wtyczkę w „Wtyczki → Zainstalowane wtyczki”. Sama kolekcja nie renderuje niczego, więc przed dodaniem ikon nie zobaczysz żadnej zmiany.

2. Zarejestruj ikony na dwa sposoby

Ikona SVG wpisana bezpośrednio w PHP

Serce możesz przechowywać bezpośrednio w pliku PHP. To rozsądna opcja, gdy masz jedną lub dwie ikony i nie chcesz tworzyć dodatkowych plików.

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>',
        )
    );
}

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>',
        )
    );
}

Hook init uruchamia tę funkcję z priorytetem 20, czyli później niż rejestrację kolekcji z domyślnym priorytetem 10. Nazwa myplugin/heart ma format kolekcja/slug-ikony, a label opisuje ikonę w selektorze. Atrybut stroke="currentColor" każe SVG przejąć kolor otaczającego tekstu, zamiast wymuszać kolor w samym pliku.

Ikony z plików SVG

Gdy ikony leżą na dysku, przekaż do API file_path. Zapisz poniższe pliki w katalogu icons/.

<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">
    <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>

<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',
        )
    );
}

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',
        )
    );
}

Mechanizm rejestracji pozostaje taki sam, zmienia się tylko content na file_path. WordPress odczyta plik wtedy, gdy będzie potrzebował ikony. Po otwarciu bloku core/icon w edytorze zobaczysz sekcję „MyPlugin” z ikonami Heart, Star i Bookmark.

Jeżeli ikony nie ma w selektorze, najczęściej została dodana przed utworzeniem kolekcji. Zostaw rejestrację kolekcji przy domyślnym priorytecie, a rejestrację ikon ustaw później, na przykład na 20.

Sekcja własnych ikon w selektorze bloku WordPressa — Własne ikony pojawiają się jako osobna sekcja selektora. — *Forrás: WPVibes*

3. Rejestruj cały katalog ikon automatycznie

Ręczne wywołanie wp_register_icon() dla kilkudziesięciu ikon szybko staje się uciążliwe. Zamiast funkcji myplugin_register_file_icons() użyj pętli, która na każdym żądaniu znajdzie wszystkie pliki SVG w katalogu.

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,
            )
        );
    }
}

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' ) zwraca wszystkie pliki .svg z katalogu. Następnie basename( $file_path, '.svg' ) pobiera nazwę bez rozszerzenia, więc advanced-button.svg zmieni się w advanced-button.

Wyrażenie ucwords( str_replace( '-', ' ', $slug ) ) tworzy czytelną etykietę dla selektora: z advanced-button powstaje „Advanced Button”. Pętla rejestruje każdą ikonę w kolekcji myplugin/. Dodaj nowy SVG do katalogu, odśwież edytor i wybierz go bez zmiany kodu.

Ten wzorzec obsługuje całą bibliotekę ikon: serce nadal może pochodzić z kodu wpisanego bezpośrednio w PHP, a gwiazdka, zakładka i kolejne pliki trafiają do rejestru automatycznie. Sześć kluczowych linii wystarczy zarówno dla trzech, jak i trzystu ikon.

Wiele własnych ikon SVG w selektorze WordPressa — Masowa rejestracja udostępnia wszystkie pliki z katalogu. — *Forrás: WPVibes*

4. Użyj zarejestrowanych ikon w trzech miejscach

W bloku core/icon i przez REST API

Selektor bloku core/icon automatycznie pokazuje każdą zarejestrowaną kolekcję. Wstaw ikonę z sekcji „MyPlugin”, a blok wyrenderuje ją na froncie bez dodatkowego kodu.

Ikony są także dostępne dla narzędzi zewnętrznych, które odczytują dane WordPressa, pod endpointem REST /wp-json/wp/v2/icons. Kolekcje zwraca towarzyszący endpoint /wp-json/wp/v2/icon-collections.

W szablonach PHP przez wp_get_icon()

Funkcja wp_get_icon() zwraca SVG jako string, dlatego w najprostszym przypadku możesz od razu użyć echo.

echo wp_get_icon( 'myplugin/heart' );

echo wp_get_icon( 'myplugin/heart' );

Drugi argument pozwala ustawić rozmiar, klasę CSS oraz opis dostępności.

echo wp_get_icon(
    'myplugin/star',
    array(
        'size'  => 32,
        'class' => 'featured-icon',
        'label' => __( 'Featured', 'myplugin-icons' ),
    )
);

echo wp_get_icon(
    'myplugin/star',
    array(
        'size'  => 32,
        'class' => 'featured-icon',
        'label' => __( 'Featured', 'myplugin-icons' ),
    )
);

size ustawia atrybuty width i height SVG w pikselach.
class dodaje klasę CSS do elementu SVG.
label ustawia aria-label dla czytników ekranu.

Możesz także udostępnić ikonę autorom treści przez shortcode myplugin_icon. Kod sanitizuje nazwę ikony, klasę i rozmiar, a przy braku ikony zwraca pusty string.

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'] )
    );
}

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'] )
    );
}

Shortcode działa w każdym wpisie, stronie i widżecie:

[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"]

[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 pojawi się obok tekstu w rozmiarze z atrybutu size. Dzięki currentColor automatycznie przyjmie kolor tekstu otaczającego shortcode.

Jako ikona własnego bloku

W register_block_type() możesz zastąpić domyślny Dashicon nazwą zarejestrowanej ikony. Zamiast poniższego wpisu:

'icon' => 'warning', // Używa Dashiconu

'icon' => 'warning', // Używa Dashiconu

użyj pełnej nazwy ikony z kolekcji:

'icon' => 'myplugin/star', // Używa zarejestrowanej ikony własnej

'icon' => 'myplugin/star', // Używa zarejestrowanej ikony własnej

Inserter bloków pokaże wtedy własny SVG zamiast ogólnego Dashiconu. Działa to zarówno dla bloków rejestrowanych w JavaScripcie, jak i bloków tworzonych wyłącznie w PHP. Jedna rejestracja zasila więc edytor, PHP i REST API – podobny model stosuje Abilities API.

5. Dopasuj ikony przez CSS

Ikony wyglądają naturalnie, gdy dziedziczą kolor tekstu, skalują się z otoczeniem i reagują na interakcję. Argument class z wp_get_icon() daje bezpośredni hook CSS, a style możesz stosować także do ikon w edytorze, gdzie tego argumentu nie używasz.

Korzystaj z currentColor

W SVG używaj stroke="currentColor" albo fill="currentColor", a nie kolorów zapisanych na stałe. SVG zachowuje się wtedy jak tekst: wewnątrz czerwonego tekstu będzie czerwony, w ciemnym motywie ciemny, a w linku przyjmie kolor linku.

<!-- Kolor zapisany na stałe: ikona zawsze będzie czerwona -->
<svg viewBox="0 0 24 24"
     stroke="#dc2626"
     stroke-width="2">
    <path d="..."/>
</svg>

<!-- Kolor zapisany na stałe: ikona zawsze będzie czerwona -->
<svg viewBox="0 0 24 24"
     stroke="#dc2626"
     stroke-width="2">
    <path d="..."/>
</svg>

Brak twardo zakodowanych kolorów odróżnia ikonę pasującą do każdego motywu od ikony, która gryzie się z częścią motywów.

Wymuś kolor, gdy wymaga tego kontekst

Znak marki albo wskaźnik statusu może wymagać stałego koloru niezależnie od otoczenia. Ustaw wtedy color na SVG przez klasę przekazaną w wp_get_icon().

.featured-icon {
    color: #f59e0b; /* Bursztynowy niezależnie od koloru tekstu */
}

.featured-icon {
    color: #f59e0b; /* Bursztynowy niezależnie od koloru tekstu */
}

Ponieważ SVG używa currentColor, właściwość color przeniesie się na jego stroke lub fill. Ikona będzie bursztynowa nawet w ciemnym tekście.

Rozmiar i stan hover

Dla ikon wyrenderowanych przez shortcode lub wp_get_icon() dokładny rozmiar w pikselach ustawisz argumentem size. Gdy chcesz sterować skalą z CSS albo dodać efekt hover, użyj reguł takich jak poniżej.

.myplugin-icon-inline svg {
    transition: transform 0.15s ease-in-out;
}

.myplugin-icon-inline:hover svg {
    transform: scale(1.1);
}

.myplugin-icon-inline svg {
    transition: transform 0.15s ease-in-out;
}

.myplugin-icon-inline:hover svg {
    transform: scale(1.1);
}

Użyj size w wp_get_icon(), gdy jednorazowo potrzebujesz konkretnego rozmiaru i nie warto tworzyć stylu CSS.
Użyj klas CSS – przekazanych przez class albo dodanych do elementu opakowującego – gdy ikona występuje w wielu miejscach, ma wyglądać spójnie lub styl zależy od stanu hover, focus, active czy kontekstu, na przykład linku albo nagłówka.
W shortcode drobne zmiany w pojedynczym użyciu obsłuży size, a spójny wygląd całej witryny zapewnią reguły dla .myplugin-icon-inline svg.

6. Usuń ikonę lub całą kolekcję

Usuń pojedynczą ikonę

Podczas prac deweloperskich albo gdy aktualizacja wtyczki wycofuje ikonę, wyrejestrujesz ją jednym wywołaniem:

wp_unregister_icon( 'myplugin/bookmark' );

wp_unregister_icon( 'myplugin/bookmark' );

Ikona zniknie z selektora przy następnym żądaniu. Wpisy, które już zawierają tę ikonę w bloku core/icon, wyrenderują pustą zawartość, ponieważ WordPress nie przepisuje treści wpisów.

Usuń kolekcję przy dezaktywacji

Po dezaktywacji wtyczki jej ikony nie powinny pozostać w selektorze. Wyrejestrowanie kolekcji usuwa wszystkie jej ikony naraz, więc nie musisz iterować po każdej z nich.

register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );

function myplugin_unregister_icons() {
    wp_unregister_icon_collection( 'myplugin' );
}

register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );

function myplugin_unregister_icons() {
    wp_unregister_icon_collection( 'myplugin' );
}

7. Przygotuj SVG bezpieczny i przenośny

WordPress nie modyfikuje SVG podczas rejestracji. Udostępnia dokładnie string przekazany w content albo zawartość pliku wskazanego przez file_path, dlatego przed wydaniem samodzielnie oczyść ikony z niepotrzebnych elementów.

Usuń twardo ustawione kolory fill i stroke; jako odwołanie do koloru stosuj currentColor.
Usuń width i height z głównego elementu <svg>, ale zachowaj viewBox.
Usuń bloki <style>, skrypty, zewnętrzne referencje i wszystko, co nie jest potrzebne.
Zachowaj viewBox oraz atrybuty opisujące strukturę grafiki.

Jeżeli wolisz rejestrować ikony z motywu, ten sam wp_register_icon() wywołaj w functions.php, a ścieżkę do pliku zbuduj przez get_stylesheet_directory(). Pamiętaj jednak, że po zmianie motywu te ikony znikną.

Najważniejsze zasady

Najpierw utwórz kolekcję, dopiero potem dodawaj do niej ikony.
Stosuj content dla SVG wpisanego bezpośrednio w PHP, a file_path dla plików na dysku; oba warianty mogą współistnieć w jednej kolekcji.
Zamiast pojedynczych wywołań dla każdej ikony użyj glob() na katalogu SVG, aby skalować bibliotekę bez zmieniania kodu.
wp_get_icon( $name, $args ) zwraca string SVG i przyjmuje między innymi size, class, label ustawiający aria-label oraz title.
Projektuj SVG z currentColor, aby ikona dopasowywała się do otoczenia.
Jedna rejestracja udostępnia ikonę edytorowi, PHP i REST API.

Pobierz kompletną przykładową wtyczkę z ikonami SVG, plikiem README i pełnym wzorcem masowej rejestracji, a następnie przetestuj ją na WordPressie 7.1. Po wdrożeniu zachowaj nazwy kolekcji specyficzne dla wtyczki – właśnie one chronią bibliotekę ikon przed konfliktami z core WordPressa i innymi rozszerzeniami.

Kompletna przykładowa wtyczka na GitHubie