Hands-on With the WordPress 7.1 Icon Registration API

Hands-on With the WordPress 7.1 Icon Registration API ![rw-book-cover](https://developer.wordpress.org/news/files/2026/08/icon-registration-api.png) 🔗 **Source:** [Hands-on With the WordPress 7.1 Icon Registration API](https://developer.wordpress.org/news/2026/08/hands-on-with-the-wordpress-7-1-icon-registration-api/) > [!note]+ Document Notes > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > # 🏷️ Title: Hands-on with the WordPress 7.1 Icon Registration API >  ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - `wp_register_icon_collection()` / `wp_register_icon()` — the two new WP 7.1 core functions this tutorial teaches - "Registering and rendering SVG icons in WordPress 7.1" — the linked developer note for full API coverage - The tutorial's own GitHub repo (`wptrainingteam/devblog-restaurant-icons`) — complete example plugin code - Google's Material Icons library — source of the demo restaurant icon set - Open PR referenced for expanding the SVG element allowlist beyond `<svg>`/`<path>`/`<polygon>` ## 📝 Summary - **What happened.** WordPress 7.1 ships a public API (`wp_register_icon_collection()` + `wp_register_icon()`) for registering custom icon collections for the Icon block, closing a gap left when the Icon block itself shipped in 7.0 with no way to add icons beyond the built-in set. The article is a hands-on tutorial that walks through registering icons and building a complete example plugin using a PHP 8.1 backed enum instead of arrays or magic strings. - **Why it matters.** This removes a concrete extensibility gap for theme/plugin developers who want the Icon block to support their own icon sets, and demonstrates a specific, opinionated pattern (backed enum with per-case methods) for representing that kind of registry data type-safely. - **Stakeholders.** Theme and plugin developers extending the Icon block; WordPress Core (the API surface being documented); site builders who will consume the resulting UI (Icon Library → collection tabs). - **Risks.** The API ships with real, stated limitations — restricted SVG element allowlist, stripped `stroke` attribute, no editor component for embedding icons inside other blocks yet — that the article is explicit about rather than glossing over. - **Bottom line.** A genuinely complete, working extensibility API lands in 7.1, with sanitization and componentization work still ongoing for 7.2+. ## 📖 Main Content ### 🗒️ Notes - **The gap being closed.** WP 7.0's Icon block shipped with a fixed icon list and no public registration API — a stated frustration for the author ("a bit of a letdown"). - **Two-function registration model.** `wp_register_icon_collection(string $slug, array $args)` registers a namespace (label + description); `wp_register_icon(string $icon_name, array $icon_properties)` registers an individual icon under a collection-prefixed name (`collection-slug/icon-slug`), taking either inline `content` (SVG markup) or a `file_path`. - **Registration timing.** Both calls belong on the `init` hook — standard WordPress registration-pattern placement. - **Block markup output.** A registered icon renders as `` — the collection/icon slug pair is the only state persisted in block markup. - **The example plugin's architecture.** Rather than a plain array or manifest, the tutorial builds a PHP 8.1 string-backed `enum Icon` with per-case `label()`, `handle()`, and `filePath()` methods (each via `match()`), plus `COLLECTION` and `ICONS_PATH` constants — then a single `IconRegistrar` class loops `Icon::cases()` on `init` to register everything. - **The stated case for the enum over an array.** `Icon::Cake` is a checkable type PHP validates and IDEs autocomplete; `$icons['cake']` is "just a string a typo... can silently break with no error until runtime." PHP's `match()` also warns (statically or via `UnhandledMatchError`) if a case goes unhandled. - **Output patterns.** In block context: ``. Outside block context: `wp_get_icon(Icon::Cake->handle(), ['size' => 32])`. - **Stated 7.1 limitations (explicit, not implied).** 1. SVG element allowlist restricted to `<svg>`, `<path>`, `<polygon>` — no formal SVG-sanitization function exists yet in core; a PR is in progress to add more elements (e.g. `<circle>`, `<rect>`) with sanitization. 2. `stroke` attribute is stripped (tied to the same sanitization gap) — icons must be `fill`-based for now; `fill` itself is stripped from the outer `<svg>` (styled via CSS instead) but survives on `<path>`/`<polygon>`. 3. No built-in editor component yet for embedding icons inside other blocks (beyond the standalone Icon block) — experimental work and open tickets exist; read-only REST API endpoints for icons are available now. ## 📚 References - `wp_register_icon_collection()`, `wp_register_icon()`, `wp_get_icon()` — the three core functions this API introduces - "Registering and rendering SVG icons in WordPress 7.1" developer note — primary technical reference for the full API surface - `wptrainingteam/devblog-restaurant-icons` GitHub repo — the complete working example ## 🗣️ Paraphrase WordPress 7.1 finally gives developers a public way to add their own icons to the Icon block that shipped in 7.0 without one. The API is small — one function to register a named collection, one to register individual icons into it, each icon defined by a label plus either inline SVG or a file path — and both calls belong on the `init` hook like any other WordPress registration pattern. The tutorial's real contribution is showing a specific, opinionated way to organize a plugin's icon data: instead of an array of strings that can typo silently, it uses a PHP backed enum where each icon case carries its own label, full collection-qualified handle, and file path via small per-case methods, so referencing an icon becomes a checkable, autocompletable expression rather than a magic string. The piece is also honest about what's not finished yet — the SVG sanitizer only allows three element types today, stroke-based icons don't work, and there's no dedicated editor component for putting icons inside other blocks — framing 7.1 as a real but partial step with concrete follow-up work already visible in open PRs and tickets. ## 📰 Newsletter **The Icon block finally gets a real extensibility story.** WordPress 7.1 ships `wp_register_icon_collection()` and `wp_register_icon()` — the public API the Icon block needed since it launched in 7.0 with a fixed, closed icon set. This walkthrough builds a complete restaurant-menu icon plugin from scratch, and its best idea has nothing to do with icons specifically: instead of an array of icon-name strings (typo-prone, no autocomplete, fails silently), it models the whole icon set as a PHP 8.1 backed enum, with `label()`, `handle()`, and `filePath()` methods baked onto each case via `match()`. Add a case, get a compiler-checked, IDE-autocompleted reference everywhere in your codebase — and PHP will flag an unhandled case for you. The honest caveats matter too: SVG sanitization is still limited to three element types, `stroke`-styled icons don't work yet, and there's no dedicated block-embedding component — all flagged as active 7.2+ work, not glossed over. ## ✅ Action Items This IS a WordPress source. Organized by relevant subteam(s) from the full list (Core, Core Performance, Core AI, Core Program Team, Mobile, Playground, Community, Training, Marketing, Support, Design, Documentation, Photos, TV, Polyglots, Accessibility, Meta, CLI, Hosting, Tide, Openverse, Themes, Plugins) / The WPOCC / FAIR — only genuinely implicated subteams populated, rest not applicable: - **Core**: Track the SVG-sanitization PR (allowlist expansion to `<circle>`, `<rect>`, etc.) — this is the single biggest limiting factor named in the article for 7.1's real-world usability. - **Documentation**: Ensure `wp_register_icon_collection()`/`wp_register_icon()`/`wp_get_icon()` land in the core function-reference docs with the same clarity as this tutorial, not just the linked developer note. - **Themes / Plugins**: Theme and plugin authors targeting 7.1+ should evaluate whether their existing icon-handling code (custom icon fonts, inline SVG sprites) should migrate to the new registration API now, ahead of the editor-component work landing in 7.2+. - Not applicable: Core Performance, Core AI, Core Program Team, Mobile, Playground, Community, Training, Marketing, Support, Design, Photos, TV, Polyglots, Accessibility, Meta, CLI, Hosting, Tide, Openverse, The WPOCC, FAIR — no content in this source implicates these teams directly (Design/Accessibility are adjacent via the icon UI itself but the article doesn't raise accessibility concerns about the Icon block specifically). ## 🧪 Hypotheses 1. Plugins/themes that migrate to `wp_register_icon()` from ad-hoc icon-font or inline-SVG-sprite systems will see fewer icon-related support tickets tied to icon-name typos, since the enum-based reference pattern is statically checkable. 2. The stated SVG-sanitization PR, once merged, will be a precondition for a meaningful fraction of currently-blocked custom-icon use cases (anything needing `<circle>`/`<rect>`/`stroke`) to become viable without hacks. 3. Adoption of the backed-enum pattern shown here will correlate with PHP 8.1+ minimum-version requirements in the plugin's own `Requires PHP` header, since backed enums require 8.1. 4. The lack of an editor component for embedding icons inside other blocks (vs. only the standalone Icon block) will be cited as a blocker in 7.2 development-cycle planning discussions. ## 📊 Methodology Not applicable to this source — this is a hands-on developer tutorial with worked code examples, not an empirical study. Its claims are about API surface and behavior, verifiable by reading WordPress core source directly rather than through a research methodology. ## ❓ Questions - Once the SVG-sanitization PR lands, will `stroke`-based icons become fully supported, or will there be a narrower allowlist even then? - Does the read-only REST API for icons (mentioned in passing at the end) expose enough for a third-party icon-picker UI to be built today, ahead of the native editor component? - How does icon registration interact with block theme `theme.json` — can collections/icons be declared declaratively, or is `wp_register_icon()` PHP-only in 7.1? - Is there a deregistration function (`wp_unregister_icon()` or similar) for cases where a plugin needs to remove/override a previously registered icon? ## 🔮 Future Research - A follow-up piece once the SVG-sanitization PR merges, covering the expanded element allowlist and whether `stroke`-based icons become practical. - A comparison of this backed-enum registration pattern against how other WordPress core registries (post types, taxonomies, blocks) could benefit from the same type-safety approach, or why they don't already use it. - Tracking the promised editor-component work for embedding icons inside arbitrary blocks (not just the standalone Icon block) as it lands in 7.2 planning. ## 💡 Implications - **Practice.** Directly actionable today — theme/plugin developers building on 7.1+ have a real, complete (if partial) icon-registration API and a demonstrated type-safe pattern to copy. - **Policy/governance.** None directly — this is a core feature-adoption story, not a governance question. - **Education.** The backed-enum pattern is a reusable teaching example for "why enums over arrays for closed sets of related data" that extends well beyond icons — genuinely general PHP practice advice smuggled into a WordPress-specific tutorial. - **Security.** The explicit SVG-sanitization gap (only `<svg>`/`<path>`/`<polygon>` allowed, no formal sanitizer function in core yet) is itself a security-relevant detail — it means the current restriction is a safety measure, not an oversight, and expanding the allowlist is correctly gated on the sanitizer work landing first. ## 🧠 Learning Styles Assessment - **Visual:** Strong — multiple screenshots of the Icon block UI and Icon Library modal illustrate the end-user-visible result of the code. - **Aural:** Weak — this is a dense code-and-prose tutorial, not naturally suited to being read aloud. - **Verbal:** Strong — precise technical vocabulary (collection, handle, backed enum, match expression) used consistently and defined on first use. - **Kinesthetic:** Strong — the entire piece is a build-along tutorial with copyable code at every step, explicitly designed for hands-on following. - **Logical:** Strong — the argument for enums over arrays is a genuine logical case (type-checkability, autocomplete, static/runtime unhandled-case detection), not just an assertion. - **Social:** Weak — no community discussion, comments, or collaborative framing; a solo tutorial voice throughout. - **Solitary:** Strong — designed for a developer to work through alone at their own pace, referencing the linked GitHub repo as needed. - **Naturalistic:** Weak — no ecological/systems framing; purely a code-level API tutorial. - **Reading level estimate:** Approximately Flesch-Kincaid grade 11-12 — technical vocabulary and code density push this above general-audience prose, appropriate for its intermediate/advanced PHP-developer target audience. ## 📊 Accessibility Assessment (WCAG 2.2 AA) - **Text alternatives:** Screenshots described with adjacent alt-text-style captions in the source (e.g., "WordPress post editor showing a restaurant menu...") — present but not independently verifiable as full WCAG-compliant alt text from the scraped content alone. - **Adaptable/reflow:** Code blocks and prose reflow as standard HTML; no fixed-width or non-reflowing elements evident. - **Distinguishable (contrast/color):** Not assessable from scraped text; code syntax highlighting (if present on the live page) would need independent contrast verification. - **Predictable navigation:** Standard technical-blog layout with a clear Table of Contents up front — predictable and well-signposted. - **Input assistance:** N/A — no interactive forms in the article body. - **Time-based media:** N/A — no audio/video in this piece. - **Compatible (parsing):** Clean semantic HTML (headings, code blocks, lists); no custom widgets or ARIA-dependent interactive elements evident in the body text. ## 🌍 DEIB Assessment - **Cultural breadth:** Narrow but appropriately scoped — this is a technical API tutorial with no cultural claims to make; the restaurant-menu example (bakery, bento, ramen, kebab, tapas icons) draws on a genuinely multicultural food vocabulary as demo content, incidentally. - **Inclusive language:** Neutral throughout; standard technical register. - **Neurodiversity support:** The clear Table of Contents, consistent code-block formatting, and step-by-step structure support readers who benefit from predictable, chunked information — a genuine (if likely unintentional) accessibility strength of the tutorial format itself. - **Representation:** Not applicable — no people are discussed or represented in this content beyond the anonymous "you" of the tutorial address. - **Psychological safety:** Not applicable to this source type. ## ✅ Logical Validity - **Strong reasoning:** The enum-vs-array argument is well-supported with concrete failure modes (silent typo breakage vs. static/runtime detection) rather than asserted as a stylistic preference alone. - **Fallacies:** None identified — this is a technical tutorial making falsifiable, checkable claims about API behavior (verifiable by reading WordPress core source directly), not an argumentative piece susceptible to the fallacy categories this framework usually screens for. - **Tone of voice:** Enthusiastic but grounded — opens with genuine excitement ("one of the most exciting moments I'd felt in a while") balanced by explicit acknowledgment of limitations throughout, rather than one-sided feature-marketing. ## 🛡️ DARVO Analysis Not applicable to this source — a technical tutorial with no accusation, conflict, or defensive posture present. ## 🎯 Conclusion - **Bottom line.** WordPress 7.1's Icon Registration API is a real, working extensibility win for the Icon block, demonstrated end-to-end with a complete example plugin — and the tutorial's most transferable lesson (backed enums over arrays for type-safe closed registries) is good general PHP practice independent of the WordPress-specific API it's teaching. - **Practical next steps.** Theme/plugin developers targeting 7.1+ can adopt this pattern today; watch the SVG-sanitization PR and the editor-component tickets for the two biggest named gaps to close in upcoming releases. ## 🔄 Refactor Appendix — Hands-on with the WordPress 7.1 Icon Registration API > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. Resonance filter: if you can't > articulate in one line why a claim matters, drop it. > > Konik claim-header rules: present tense, declarative, ≤10 words when > possible, searchable, unique, mirrors annotation focus if present. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### [H1] Backed enums beat arrays for closed, type-checked registries > [!quote] ID:rw_atom1 > 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. **Context & use**: - The article's core architectural argument for why the example plugin uses a PHP 8.1 backed enum instead of an array or constants to represent its icon set. - Matters because it's a general, reusable PHP-practice claim (not WordPress-specific) about representing closed sets of related data safely. **Tags**: #xref **Highlight**: [view highlight](readwise://)  #### [H2] The Icon block shipped in 7.0 with no registration API > [!quote] ID:rw_atom2 > 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. **Context & use**: - Sets up the entire article's premise — the gap 7.1's new API closes. - Matters as a concrete, dated example of core shipping a feature ahead of its extensibility surface, then following up a release later. **Tags**: #xref **Highlight**: [view highlight](readwise://)  #### [H3] SVG sanitization gaps limit the API's element allowlist today > [!quote] ID:rw_atom3 > Currently, only <svg>, <path>, and <polygon> are allowed elements for an SVG icon. Everything else is stripped out. Part of this is because WordPress does not yet have a formal function for sanitizing SVGs. **Context & use**: - The single biggest stated limitation of the 7.1 API, tied explicitly to a security/sanitization gap rather than a design choice. - Matters because it shows the restriction is deliberate safety-gating, not an oversight — directly relevant to any security-focused reading of new core APIs. **Tags**: #xref **Highlight**: [view highlight](readwise://)  ### 🧠 Permanent Candidates (H4) #### [P1] A backed enum makes a closed registry statically checkable where an array cannot **Claim** (one sentence, Courtney's voice): When a codebase needs a closed, known set of related items (icons, statuses, roles), representing it as a PHP backed enum with per-case methods catches typos and unhandled cases at compile/static-analysis time that an array of string keys would only surface as a silent runtime failure. **Evidence pointer**: [[#H1]] **Scope & conditions**: Holds when the set is genuinely closed (adding a new item is a deliberate code change, not runtime-dynamic data) and the codebase targets PHP 8.1+. Breaks when the set must be extensible at runtime by third parties without a code change (e.g., truly open plugin-registered taxonomies) — an enum can't represent data that isn't known at write time. **Links** (≥1 with annotation): - no existing vault note identified — flag for synthesis pass (closest adjacent territory is general "context not constraints" / type-safety threads in AI & the Future of Knowledge Work MOC, but no direct match found)  ### ✏️ Fleeting Queue - [F1] Check whether `wp_register_icon()` interacts with block theme `theme.json` declaratively, or is PHP-registration-only in 7.1 — #xref - [F2] Track the SVG-sanitization PR and the icon-editor-component tickets referenced at the end of the article for a 7.2-cycle follow-up note — #articleseed ### → Things 3 (max 2 actions) - [ ] None — no direct action item for Courtney's own work from this source; logged for the vault's WordPress-core-features tracking only.  📄 **Full text:** [[Full Document Contents/Articles/Hands-on With the WordPress 7.1 Icon Registration API.md|Hands-on With the WordPress 7.1 Icon Registration API by WordPress.org Developer Blog]] ## Highlights - 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. ([View Highlight](https://read.readwise.io/read/01m0bb7nqsnknr61em3wtf6fr9)) - Note: Sets up the article's premise — the gap 7.1's new registration API closes. - Tags: atom/literature/h1 - 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. ([View Highlight](https://read.readwise.io/read/01m0bb7s6vc6mpdccvj37cz5p8)) - Note: Core architectural argument for backed enums over arrays — general PHP practice, not WordPress-specific. - Tags: atom/literature/h1 - Currently, only `<svg>`, `<path>`, and `<polygon>` are allowed elements for an SVG icon. Everything else is stripped out. Part of this is because WordPress does not yet have a formal function for sanitizing SVGs. This is likely the biggest limiting factor for highly custom icons in 7.1. ([View Highlight](https://read.readwise.io/read/01m0bb7wgrtyfbggwdq32259mr)) - Note: The biggest stated limitation, tied explicitly to a security/sanitization gap rather than a design choice. - Tags: atom/literature/h2