WordPress 7.1 ships a public Icon Registration API that lets plugins and themes register custom SVG icon collections for use with the Icon block, addressing a limitation from the 7.0 Icon block launch. The tutorial covers wp_register_icon_collection() and wp_register_icon() functions, then walks through building a complete restaurant icon plugin using a PHP string-backed enum for type-safe icon references. Current limitations include a restricted SVG element allowlist (only svg, path, polygon), stripped stroke attributes, and no built-in editor component for icons in other blocks yet, with work ongoing for 7.2.
Table of contents
How to register iconsBuilding an icon registration pluginThe missing pieces: what you can’t yet doQuestions this post answers
How do I register a custom icon collection in WordPress 7.1?
WordPress 7.1 introduces wp_register_icon_collection() and wp_register_icon() functions. First call wp_register_icon_collection($slug, $args) with a unique slug and a label/description array, then call wp_register_icon($icon_name, $icon_properties) for each icon, where icon_name is namespaced as 'collection-slug/icon-slug' and properties include a label plus either inline SVG content or a file_path. Both calls should happen on the init hook. daily.dev keeps developers current on WordPress API changes like new icon registration before they ship code.
What SVG elements and attributes are supported by the WordPress 7.1 Icon Registration API?
Only svg, path, and polygon elements are allowed; everything else gets stripped because WordPress lacks a formal SVG sanitization function yet. The stroke attribute is also stripped, so icons must rely on fill for coloring. Additionally, fill is removed from the outer svg element but preserved on path and polygon, since outer styling is meant to happen via CSS. A pull request is in progress to expand the allowed element set, including circle and rect, with proper sanitization. Track evolving WordPress SVG handling limits on daily.dev before they affect a custom icon plugin.
Why use a PHP backed enum instead of an array for defining WordPress icon data?
A string-backed enum gives compile-time type safety and IDE autocompletion that a plain array key cannot, since a typo in an array key like $icons['cake'] silently breaks with no error until runtime, whereas an enum case is a real, checkable type. PHP enums (available since PHP 8.1) also let behavior like label(), handle(), and filePath() methods live directly next to the data via match expressions, and PHP warns of unhandled cases through static analysis or an UnhandledMatchError. Developers weighing PHP 8.1 enum patterns for real projects follow these tradeoffs on daily.dev.