Title: Hands-on with the WordPress 7.1 Icon Registration API
Author: Justin Tadlock
Published: August 18, 2026
---
* [Showcase](https://wordpress.org/showcase/)
* [Plugins](https://wordpress.org/plugins/)
* [Themes](https://wordpress.org/themes/)
* [Hosting](https://wordpress.org/hosting/)
* [News](https://wordpress.org/news/)
- [Learn WordPress](https://learn.wordpress.org/)
- [Documentation](https://wordpress.org/documentation/)
- [Education](https://wordpress.org/education/)
- [Forums](https://wordpress.org/support/forums/)
- [Developers](https://developer.wordpress.org/)
- [Blocks](https://wordpress.org/blocks/)
- [Patterns](https://wordpress.org/patterns/)
- [Photos](https://wordpress.org/photos/)
- [Openverse ︎](https://openverse.org/)
- [WordPress.tv ︎](https://wordpress.tv/)
* - [About WordPress](https://wordpress.org/about/)
- [Make WordPress](https://make.wordpress.org/)
- [Events](https://events.wordpress.org/)
- [Five for the Future](https://wordpress.org/five-for-the-future/)
- [Enterprise](https://wordpress.org/enterprise/)
- [Gutenberg ︎](https://wordpress.org/gutenberg/)
- [Job Board ︎](https://jobs.wordpress.net/)
* [Swag ︎](https://mercantile.wordpress.org/)
* [Get WordPress](https://wordpress.org/download/)
Search in WordPress.org
[ Get WordPress ](https://wordpress.org/download/)
[WordPress Developer Blog](https://developer.wordpress.org/news)
Hands-on with the WordPress 7.1 Icon Registration API
* [Snippets](https://developer.wordpress.org/news/snippets/)
- [Blocks](https://developer.wordpress.org/news/category/blocks/)
- [Concepts](https://developer.wordpress.org/news/category/concepts/)
- [Common APIs](https://developer.wordpress.org/news/category/common-apis/)
- [Design](https://developer.wordpress.org/news/category/design/)
- [Playground](https://developer.wordpress.org/news/category/playground/)
- [Plugins](https://developer.wordpress.org/news/category/plugins/)
- [Themes](https://developer.wordpress.org/news/category/themes/)
* - [About this site](https://developer.wordpress.org/news/about/)
- [Updates](https://developer.wordpress.org/news/category/updates/)
- [How to contribute](https://developer.wordpress.org/news/how-to-contribute/)
- [Tips and guidelines](https://developer.wordpress.org/news/tips-and-guidelines-for-writers/)
* [Subscribe](https://developer.wordpress.org/news/subscribe/)
* [Developer Resources](https://developer.wordpress.org/)
* [Snippets](https://developer.wordpress.org/news/snippets/)
- [Blocks](https://developer.wordpress.org/news/category/blocks/)
- [Concepts](https://developer.wordpress.org/news/category/concepts/)
- [Common APIs](https://developer.wordpress.org/news/category/common-apis/)
- [Design](https://developer.wordpress.org/news/category/design/)
- [Playground](https://developer.wordpress.org/news/category/playground/)
- [Plugins](https://developer.wordpress.org/news/category/plugins/)
- [Themes](https://developer.wordpress.org/news/category/themes/)
* - [About this site](https://developer.wordpress.org/news/about/)
- [Updates](https://developer.wordpress.org/news/category/updates/)
- [How to contribute](https://developer.wordpress.org/news/how-to-contribute/)
- [Tips and guidelines](https://developer.wordpress.org/news/tips-and-guidelines-for-writers/)
* [Subscribe](https://developer.wordpress.org/news/subscribe/)
* [Developer Resources](https://developer.wordpress.org/)
# Hands-on with the WordPress 7.1 Icon Registration API
By [Justin Tadlock](https://profiles.wordpress.org/greenshady/)
August 18, 2026
[Common APIs](https://developer.wordpress.org/news/category/common-apis/), [Plugins](https://developer.wordpress.org/news/category/plugins/),
[Themes](https://developer.wordpress.org/news/category/themes/)
When WordPress 7.0 launched the Icon block earlier this year, it was one of the
most exciting moments I’d felt in a while. But it was also a bit of a letdown because
there was no public API for registering custom icons. The list of available icons
for the block felt limiting for most creative uses of it.
The good news: the public API is shipping with WordPress 7.1!
And it does nearly everything that I need for truly using it in projects, such as
this restaurant menu idea I’ve been tinkering with:
In this tutorial, I’ll walk you through some of the basics. Then you’ll learn how
to build a complete icon registration plugin from start to finish.
Table of Contents
1. [How to register icons](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#how-to-register-icons)
2. a. [A quick overview of the registration functions](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#a-quick-overview-of-the-registration-functions)
b. [An example collection and icon](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#an-example-collection-and-icon)
3. [Building an icon registration plugin](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#building-an-icon-registration-plugin)
4. a. [Plugin setup](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#plugin-setup)
b. [Bundling icons in plugin](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#bundling-icons-in-plugin)
c. [Defining the icon data structure](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#defining-the-icon-data-structure)
d. [Registering the icons with WordPress](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#registering-the-icons-with-wordpress)
e. [Load the plugin files and bootstrap](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#load-the-plugin-files-and-bootstrap)
f. [Outputting icons](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#outputting-icons)
5. [The missing pieces: what you can’t yet do](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#the-missing-pieces-what-you-can-t-yet-do)
6. a. [Allowlist of elements](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#allowlist-of-elements)
b. [Stroke attribute is stripped](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#stroke-attribute-is-stripped)
c. [No editor component…yet](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/#no-editor-component-yet)
## How to register icons
This tutorial covers the introductory layer of using the API, the relevant parts
for most use cases. For a complete overview, read the [Registering and rendering SVG icons in WordPress 7.1](https://make.wordpress.org/core/2026/07/24/registering-and-rendering-svg-icons-in-wordpress-7-1/)
developer note.
### A quick overview of the registration functions
When registering custom icons, you need to do two things:
* Register a custom icon collection, or know the slug of an existing collection
that you want to register icons for.
* Register your icons for a specific collection.
Most plugins and themes will require custom collections, which can be registered
via the `wp_register_icon_collection()` function:
```php
wp_register_icon_collection( string $slug, array $args );
```
The function has two parameters that you must pass your arguments to:
* **`$slug`:** A unique key for your plugin for your collection. Ideally, this
is prefixed with your plugin/theme name (e.g., `plugin-collection`).
* **`$args`:** An array of arguments for the collection:
- **`label`:** A human-readable and internationalized label for the collection,
which is used in the UI.
- **`description`:** An internationalized string describing the collection.
Once you have a collection, you’ll use `wp_register_icon()` to register individual
icons:
```php
wp_register_icon( string $icon_name, array $icon_properties );
```
It also has two parameters:
* **`$icon_name`:** A collection-namespaced identifier for an icon. It must start
with a collection slug, followed by a `/` (e.g., `plugin-collection/icon-slug`).
* **`$icon_properties`:** An array of arguments to define the icon:
- **`label`:** An internationalized, human-readable label for the icon.
- **`content`:** The SVG markup for the icon (optional).
- **`file_path`:** A file path to the SVG markup for the icon (optional).
Both `content` and `file_path` are optional parameters individually, but you must
choose one or the other to actually register an icon.
### An example collection and icon
Later in this tutorial, you’ll learn how to build a complete plugin with a restaurant
icon collection. But let’s start with a short example of utilizing the functions
you just learned about.
When registering collections and icons, you should do so on the `init` hook. The
following code, either added to a plugin file or theme’s `functions.php`, will register
a Cake icon under a Restaurant collection:
```php
add_action('init', 'devblog_restaurant_icons_register');
function devblog_restaurant_icons_register(): void
{
wp_register_icon_collection('devblog-restaurant', [
'label' => __('Restaurant', 'devblog-restaurant-icons'),
'description' => __('Demo icons provided by the DevBlog Restaurant Icons plugin.', 'devblog-restaurant-icons')
]);
wp_register_icon('devblog-restaurant/cake', [
'label' => __('Cake', 'devblog-restaurant-icons'),
'content' => ''
]);
}
```
The code uses the `content` property above instead of `file_path`. For one-off examples,
that’s probably preferable because it shows the full code. You’ll use the `file_path`
property in the complete plugin example below.
To test the registered collection and icon, insert the Icon block in the Post or
Site Editor and click the **Replace** button in the block’s toolbar. You will then
see the **Icon Library** with the new **Restaurant** tab (i.e., collection):
After selecting the Cake icon, it will appear in the Icon block, which you can customize
with the existing design tools.
The generated block markup looks like this:
```language-markup
```
As you can see, both the collection and icon slug are included: `devblog-restaurant/
cake`. You can use this markup in templates or patterns, just like any other block.
As far as new development features go, this one is pretty straightforward. That’s
all you really need to know for most uses of the Icon Registration API.
But let’s dive into actually building a full project on top of this new API.
## Building an icon registration plugin
As shown earlier, I had an idea of using icons for a restaurant menu page. I knew
that a few icons sprinkled throughout the design would give it a little more visual
appeal to readers.
So I’ll walk you through how I built a plugin to add those icons. All the code is
presented below in steps, but you can also study the complete code in its [GitHub repository](https://github.com/wptrainingteam/devblog-restaurant-icons).
### Plugin setup
As with any other plugin, you must create a new folder under `wp-content/plugins`
and put a main plugin file inside it. You’ll also need a couple of sub-folders for
this project. Go ahead and create a plugin directory that is structured like this:
* `devblog-restaurant-icons/`
- `public/`
* `icon/`
- `src/`
* `plugin.php`
Now add this code to `plugin.php` via your preferred code editor:
```php
__('Bakery', 'devblog-restaurant-icons'),
self::Bento => __('Bento', 'devblog-restaurant-icons'),
self::Breakfast => __('Breakfast', 'devblog-restaurant-icons'),
self::Brunch => __('Brunch', 'devblog-restaurant-icons'),
self::Cake => __('Cake', 'devblog-restaurant-icons'),
self::Dinner => __('Dinner', 'devblog-restaurant-icons'),
self::Kebab => __('Kebab', 'devblog-restaurant-icons'),
self::Lunch => __('Lunch', 'devblog-restaurant-icons'),
self::Ramen => __('Ramen', 'devblog-restaurant-icons'),
self::Restaurant => __('Restaurant', 'devblog-restaurant-icons'),
self::RiceBowl => __('Rice Bowl', 'devblog-restaurant-icons'),
self::SoupKitchen => __('Soup Kitchen', 'devblog-restaurant-icons'),
self::Tapas => __('Tapas', 'devblog-restaurant-icons')
};
}
```
This uses [`match()`](https://www.php.net/manual/en/control-structures.match.php)
to return the internationalized text label for the current enum case.
Next, add a `handle()` method to the enum:
```php
public function handle(): string
{
return self::COLLECTION . '/' . $this->value;
}
```
Because an icon name needs to be namespaced with the collection name, we can just
prepend it here. So any time you need a reference to an icon’s full handle/name,
you can call `Icon::CaseName->handle()`.
And, finally, you need a way to reference the absolute file path to the SVG, so
add a `filePath()` method to the enum:
```php
public function filePath(): string
{
return self::ICONS_PATH . '/' . $this->value . '.svg';
}
```
Note if building this in a theme, use `get_theme_file_path("public/icon/{$this->
value}.svg")`. There’s no need for the `ICONS_PATH` constant at all.
Using a backed enum instead of an array gives `Icon` compile-time type safety and
autocompletion. For example, `Icon::Cake` is a real, checkable type that PHP validates
and IDEs can autocomplete, whereas an array key like `$icons['cake']` is just a
string a typo and can silently break with no error until runtime.
The enum also lets behavior live next to the data. Methods like `label()`, `handle()`,
and `filePath()` are defined once per case via `match`. Adding a new icon means
adding one case and one line per method, and PHP’s match will warn you (via static
analysis or a runtime `UnhandledMatchError`) if a case is left unhandled.
The enum makes the full set of valid icons closed, discoverable, and self-documenting,
rather than an open-ended set of “magic strings” scattered across arrays.
### Registering the icons with WordPress
Now that you have a type-safe, IDE-friendly representation of your icons in code,
all that’s left is letting WordPress know about it. You can do this with a small
class with the singular responsibility of registering the icons.
Create a new file under `src` with the name of `IconRegistrar.php`. Then add the
following code to it:
```php
register(...));
}
private function register(): void
{
// Register the collection.
wp_register_icon_collection(Icon::COLLECTION, [
'label' => __('Restaurant', 'devblog-restaurant-icons'),
'description' => __('Demo icons provided by the DevBlog Restaurant Icons plugin.', 'devblog-restaurant-icons')
]);
// Register icons for the collection.
foreach (Icon::cases() as $icon) {
wp_register_icon($icon->handle(), [
'label' => $icon->label(),
'file_path' => $icon->filePath()
]);
}
}
}
```
This class has a `boot()` method that, when called, adds the `register()` action
on the WordPress `init` hook. From there, it registers both the icon collection
and the individual icons.
Because you used a string-backed enum, you get the built-in static [`cases()`](https://www.php.net/manual/en/unitenum.cases.php)
method for free, which returns an array of your icon cases. So the above code only
needs to loop through each case and pass the result of each of the custom methods
into `wp_register_icon()`.
Also note that the code uses `Icon::COLLECTION` without needing to remember what
that string was when registering the collection itself. _No typos to worry about!_
### Load the plugin files and bootstrap
Last items: load the PHP files you just created and call the `IconRegistrar::boot()`
method.
At the bottom of your `plugin.php` file, add this code:
```php
# Load classes manually. In production, use an autoloader.
require_once PLUGIN_DIR . '/src/Icon.php';
require_once PLUGIN_DIR . '/src/IconRegistrar.php';
# Bootstrap services.
add_action('plugins_loaded', static function (): void {
(new IconRegistrar())->boot();
});
```
Now if you look at the **Icon Library Restaurant** tab from earlier, you should
see the full list of registered icons:
### Outputting icons
As mentioned earlier in this article, you can reference registered icons via their
names in the Icon block:
```language-markup
```
That’s often a poor development experience with larger collections because you must
remember the exact string name. And there’s no autocomplete if that string lives
in a plain array somewhere else.
With the enum, it’s easy to fix that without worrying about the exact name. To ensure
that you get the correct Cake icon, reference it like so:
```php
```
If you’re not in a block context (e.g., a classic theme or outputting as part of
a plugin in some other way), you can use the `wp_get_icon()` function:
```php
handle(), [
'size' => 32
]) ?>
```
## The missing pieces: what you can’t yet do
The Icon Registration API is super powerful at this point, allowing you to register
icons for most needs. But there are still some limitations that will ship with WordPress
7.1. These are features that are actively being worked on for version 7.2 and beyond.
### Allowlist of elements
Currently, only `