Mastering the WordPress 7.1 Icon Registration API

Getting Started with the WordPress 7.1 Icon Registration API

The WordPress 7.1 Icon Registration API provides developers with a standardized, native mechanism to register, manage, and render custom vector icon collections. When WordPress 7.0 introduced the core Icon block, developers were limited to built-in system icons because no public registration framework existed. With WordPress 7.1, themes and plugins can natively expose custom SVG sets directly to the editor’s Icon Library UI and output them safely across block templates and front-end code.

To integrate custom icons properly, developers must understand two core operations: defining a collection namespace and registering individual SVG icons under that namespace. This architectural approach keeps icons organized, avoids naming collisions between plugins, and integrates directly with Gutenberg block design controls. WordPress 7.1 Icon Registration API should be evaluated in the context of the site’s current configuration and business-critical workflows.

Understanding Core Registration Functions

The API revolves around two primary PHP functions executed during the init action hook. First, you register a collection using wp_register_icon_collection(), and then you attach icons to that collection using wp_register_icon().

The signature for registering an icon collection requires a unique string slug and an arguments array:

wp_register_icon_collection( string $slug, array $args );

The $args array accepts two standard key-value pairs:

• label: A translatable string displayed in the editor’s UI tab.
• description: A localized string describing the collection’s purpose.

Once a collection exists, individual icons are registered via wp_register_icon():

wp_register_icon( string $icon_name, array $icon_properties );

The $icon_name parameter must follow a namespaced format: collection-slug/icon-slug. The $icon_properties array requires a translatable label and either inline SVG markup supplied via the content key or an absolute file path via the file_path key.

Registering Single Icons via Content or File Path

For quick implementations or small sets, inline SVG strings passed to the content argument work well. Here is a basic example registering a restaurant icon collection on the init hook:

add_action( 'init', 'my_plugin_register_simple_icon' );
function my_plugin_register_simple_icon(): void {
    wp_register_icon_collection( 'my-restaurant', [
        'label'       => __( 'Restaurant Icons', 'my-plugin' ),
        'description' => __( 'Custom icons for restaurant menus.', 'my-plugin' ),
    ] );

    wp_register_icon( 'my-restaurant/cake', [
        'label'   => __( 'Cake', 'my-plugin' ),
        'content' => '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="M160-80q-17 0-28.5-11.5T120-120v-200q0-33 23.5-56.5T200-400v-160q0-33 23.5-56.5T280-640h160v-58q-18-12-29-29t-11-41q0-15 6-29.5t18-26.5l56-56 56 56q12 12 18 26.5t6 29.5q0 24-11 41t-29 29v58h160q33 0 56.5 23.5T760-560v160q33 0 56.5 23.5T840-320v200q0 17-11.5 28.5T800-80H160Zm120-320h400v-160H280v160Zm-80 240h560v-160H200v160Zm80-240h400-400Zm-80 240h560-560Zm560-240H200h560Z"/></svg>',
    ] );
}

Inserting this block in the Site Editor outputs standard block markup using the fully qualified identifier:

<!-- wp:icon {"icon":"my-restaurant/cake"} /-->

Building a Scalable Plugin with PHP 8.1 Enums

Hardcoding magic strings across large icon sets creates maintenance problems and runtime typos. To maintain strict compile-time checks, modern WordPress development can leverage string-backed PHP enums introduced in PHP 8.1.

Consider a plugin structure with standalone SVG files located under public/icon/:

devblog-restaurant-icons/
├── public/
│   └── icon/
│       ├── bakery.svg
│       ├── cake.svg
│       └── dinner.svg
├── src/
│   ├── Icon.php
│   └── IconRegistrar.php
└── plugin.php

Inside src/Icon.php, define a string-backed enum carrying cases, collection metadata, paths, and localized labels:

<?php
declare(strict_types=1);
namespace DevBlogRestaurantIcons;

enum Icon: string {
    case Bakery = 'bakery';
    case Cake   = 'cake';
    case Dinner = 'dinner';

    public const COLLECTION = 'devblog-restaurant';
    private const ICONS_PATH = PLUGIN_DIR . '/public/icon';

    public function label(): string {
        return match ($this) {
            self::Bakery => __( 'Bakery', 'devblog-restaurant-icons' ),
            self::Cake   => __( 'Cake', 'devblog-restaurant-icons' ),
            self::Dinner => __( 'Dinner', 'devblog-restaurant-icons' ),
        };
    }

    public function handle(): string {
        return self::COLLECTION . '/' . $this->value;
    }

    public function filePath(): string {
        return self::ICONS_PATH . '/' . $this->value . '.svg';
    }
}

Using an enum ensures that methods like handle() and filePath() centralize logic. Adding a new icon only requires defining a single case and updating the match statement; missing cases trigger static analysis warnings or unhandled match errors rather than failing silently in production.

Registering Collections Dynamically with IconRegistrar

To register the enum items with WordPress, create a service class named IconRegistrar inside src/IconRegistrar.php. This class hooks registration to the init lifecycle using the enum’s built-in cases() method:

<?php
declare(strict_types=1);
namespace DevBlogRestaurantIcons;

final class IconRegistrar {
    public function boot(): void {
        add_action( 'init', $this->register(...) );
    }

    private function register(): void {
        wp_register_icon_collection( Icon::COLLECTION, [
            'label'       => __( 'Restaurant', 'devblog-restaurant-icons' ),
            'description' => __( 'Demo icons provided by the Restaurant Icons plugin.', 'devblog-restaurant-icons' ),
        ] );

        foreach ( Icon::cases() as $icon ) {
            wp_register_icon( $icon->handle(), [
                'label'     => $icon->label(),
                'file_path' => $icon->filePath(),
            ] );
        }
    }
}

Finally, instantiate the class from your primary file, plugin.php:

<?php
/**
 * Plugin Name: DevBlog: Restaurant Icons
 * Description: WordPress 7.1+ plugin for registering icon collections.
 * Version: 1.0.0
 * Requires PHP: 8.1
 */

declare(strict_types=1);
namespace DevBlogRestaurantIcons;

defined( 'ABSPATH' ) || exit;
const PLUGIN_DIR = __DIR__;

require_once PLUGIN_DIR . '/src/Icon.php';
require_once PLUGIN_DIR . '/src/IconRegistrar.php';

add_action( 'plugins_loaded', static function(): void {
    ( new IconRegistrar() )->boot();
} );

Rendering SVG Icons in Block Templates and PHP

Once registered, icons can be rendered inside block patterns, theme templates, or PHP templates without hardcoding string paths.

Inside PHP block patterns or render callbacks, use the enum handle directly to output valid block comments:

<!-- wp:icon {"icon":"<?= Icon::Cake->handle() ?>"} /-->

When outputting icons directly in classic templates or PHP components outside of a block editor context, use the native wp_get_icon() helper function:

<?= wp_get_icon( Icon::Cake->handle(), [ 'size' => 32 ] ) ?>

This ensures consistent SVG generation while allowing runtime adjustments to attributes like size directly from server-side templates.

Limitations of the WordPress 7.1 Icon Registration API

While the initial shipping version of the WordPress 7.1 Icon Registration API unlocks core functionality, developers must be aware of key SVG sanitization and editor limits:

• Restricted SVG Elements: In WordPress 7.1, SVG content is strictly sanitized. Only <svg>, <path>, and <polygon> elements are permitted. Additional vector shapes such as <circle>, <rect>, or <g> groups are currently stripped out during processing.
• Attribute Stripping Rules: The stroke attribute is removed entirely by core sanitization in 7.1. Icons must rely on fill-based paths rather than stroked geometry. Furthermore, fill properties are stripped from the root <svg> tag but preserved on internal <path> elements, allowing CSS to control global icon sizing and color.
• Lack of Reusable React Editor Components: While icons appear inside the core Icon Block’s UI, WordPress 7.1 does not yet ship an exported React component (such as an IconPickerModal) for third-party custom blocks. Extenders building custom block inspector controls must query the read-only REST API endpoints for icons and construct custom selection UIs until standardized components land in future core updates.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.