WordPress | Custom SVG Icon API for Themes and Plugins
WordPress published a hands-on guide to the new Icon Registration API on August 18, 2026. Introduced with WordPress 7.1, the public API lets theme and plugin developers register custom SVG collections, make them available inside the Icon block, reuse them in templates and patterns, and render them elsewhere through PHP.
WordPress opens the Icon block to custom design libraries
WordPress 7.0 introduced the core Icon block, but its built-in selection was too limited for many branded websites, themes, and specialized plugins. WordPress 7.1 addresses that restriction with a public registration system that allows developers to add their own icons without creating a separate custom block for every symbol.
Each icon belongs to a named collection, helping WordPress keep assets from core, themes, plugins, and third-party libraries separated. A restaurant plugin could provide food icons, for example, while a theme could register a smaller collection designed specifically for its navigation, service cards, calls to action, or decorative patterns.
Collections and icons are registered through two new functions
Developers begin by creating a collection with wp_register_icon_collection(). The collection needs a unique slug and a readable label, while an optional description can explain its purpose inside the interface. Prefixing the slug with the theme or plugin name helps prevent conflicts with other registered libraries.
Individual assets are then added with wp_register_icon(). Every icon receives a namespaced identifier in the form collection/icon-name, an internationalized label, and either inline SVG content or an absolute path to an SVG file. Registration should run on the WordPress init hook after the collection has been created.
Registered icons become reusable across editors and templates
Once registered, a custom collection appears as its own tab in the Icon Library. Editors can search the collection, select an asset, and customize it with the design controls already available to the Icon block. The selected handle can also be placed directly in block markup, making the same icon reusable in templates and patterns.
Developers can render a registered icon outside the block editor with wp_get_icon(). The function supports options for size, additional CSS classes, and accessible labels. Leaving out the label treats the image as decorative, while adding one allows screen readers to announce icons that communicate meaningful information.
The API also supports REST access and larger icon libraries
WordPress 7.1 includes read-only REST API endpoints for retrieving registered collections and icons. This gives authenticated tools access to the same library used by the editor and can support custom interfaces, block development, or other workflows that need to browse available SVG assets.
For larger libraries, icons can be stored as individual SVG files and registered programmatically. The official tutorial demonstrates this approach with a plugin that organizes restaurant icons through a PHP enum, providing predictable handles, editor autocompletion, and a central structure for labels and file paths.
IMPORTANT: WordPress 7.1 currently permits onlysvg,path, andpolygonelements in registered icons. Other SVG elements are removed during sanitization, and thestrokeattribute is not supported, so developers should use fill-based artwork and test every asset before adding it to a production library.{alertWarning}
Daisuki's Take: What This Means for Web Designers
The Icon Registration API gives WordPress projects a more consistent way to manage one of the smallest but most repeated parts of an interface. Instead of embedding unrelated SVG files throughout a theme, developers can maintain a shared library that editors can access without leaving the block interface.
For theme and template creators, this can improve both branding and usability. A carefully prepared collection can keep navigation, feature lists, service sections, buttons, and decorative patterns visually connected while giving clients a simpler way to select approved assets.
We would still keep each collection focused and test its icons at multiple sizes, colors, and responsive breakpoints. The current sanitization rules exclude many complex SVG techniques, and WordPress does not yet provide a reusable editor component for inserting registered icons into every block, so the API remains a strong foundation rather than a complete icon-management system.
Sources and Recommended Links
- Hands-on with the WordPress 7.1 Icon Registration API | WordPress Developer Blog
- Registering and rendering SVG icons in WordPress 7.1 | WordPress Core Official Blog
- DevBlog Restaurant Icons example plugin | WordPress Training Team Official Repository
