WordPress | 7.1 Icon API Adds Custom SVG Libraries
WordPress 7.1 is opening its icon system to theme and plugin developers with a public Icon Registration API. Published on August 18, 2026, the hands-on guide shows how developers can register their own SVG collections, expose those icons inside the WordPress Icon Library, use them in templates and patterns, and render the same registered assets from PHP when building custom interfaces.
WordPress themes and plugins can create their own icon libraries
WordPress 7.0 introduced the Icon block and a built-in set of SVG icons, but developers did not have a public API for extending that library. WordPress 7.1 changes that by letting plugins and themes register custom icon collections and add individual icons to them through Core functions.
Each collection receives its own identifier, label, and optional description. Individual icons are then registered under that collection using a namespaced structure such as my-plugin/icon-name. This helps WordPress keep icons from Core, themes, plugins, and third-party libraries separated without creating naming conflicts.
Custom icons become available inside the WordPress editor
Developers register collections with wp_register_icon_collection() and individual icons with wp_register_icon(). SVG markup can be supplied directly through the content property or loaded from an SVG file using file_path, making the API suitable for both small collections and larger libraries bundled with a theme or plugin.
Once registered, the icons appear in the Icon Library used by the Icon block. Collections receive their own tabs, and users can select a custom icon just as they would one provided by WordPress Core. The selected icon can then use the existing block design controls and be referenced in block markup for templates and patterns.
The same registered icon can be reused beyond the block editor
The API is not limited to inserting icons through the visual editor. WordPress 7.1 includes wp_get_icon(), which lets developers retrieve the SVG markup for any registered icon from PHP. Options can define properties such as size, CSS classes, and an accessible label when the icon needs to be announced by screen readers.
Registered collections and icons are also exposed through REST API endpoints. This gives developers a common icon source that can be used across the editor, server-rendered interfaces, custom blocks, plugins, themes, and other tools that need access to the site's registered visual assets.
SVG support still has important limitations in WordPress 7.1
The initial public API does not support every type of SVG markup. WordPress currently sanitizes registered icons against a conservative allowlist, with only <svg>, <path>, and <polygon> elements supported. Other elements are removed during sanitization.
The stroke attribute is also stripped, which means developers should currently favor fill-based icon designs. WordPress is already working toward broader SVG support for future releases, including additional elements such as circles and rectangles, but highly complex icon libraries may need adjustments before they work correctly with WordPress 7.1.
IMPORTANT: WordPress 7.1 currently limits registered SVG icons to a restricted set of elements and attributes. Icons that depend onstroke,<circle>,<rect>, or other unsupported SVG features may need to be simplified before registration.{alertWarning}
Daisuki's Take: What This Means for Web Designers
The main design benefit is consistency. A theme or plugin can now provide a controlled icon system that appears directly inside the WordPress editing experience instead of asking users to paste SVG code, install another icon tool, or manually recreate the same visual language across pages.
For theme creators, this can be particularly useful when building templates and patterns around a defined design system. Registered icons can become reusable assets with predictable names and styling, while content editors still get a visual interface for selecting them.
We would pay close attention to the current SVG restrictions before converting an existing icon library. The API already provides a strong foundation for reusable WordPress icon systems, but choosing compatible SVG structures will be important until the sanitization support becomes broader in future releases.
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 Site
