WordPress 7.1 introduces a public Icon Registration API, but the first allowlist is intentionally narrow. The sanitizer keeps svg, path, and polygon elements with selected attributes. Stroke is stripped, unsupported elements disappear, and an outer fill can be removed even when shape-level fill survives. An icon may look correct in its source file yet render black, solid, incomplete, or empty after registration.
Use this for theme and plugin teams registering custom icons with wp_register_icon(), rendering them through the Icon block, or printing them with wp_get_icon() in navigation, patterns, templates, settings, and front-end components.
Quick answer
Start from the sanitized output, not the design file. Convert stroke-only artwork into supported filled paths when practical, remove unsupported groups, masks, gradients, style tags, and event attributes, then register a minimal SVG. Test the same icon through the editor picker, saved block markup, front-end block render, REST response, and wp_get_icon(). Add scoped CSS only after the surviving markup is known. Never weaken sanitization globally to preserve a decorative asset.
What to check first
- Save the original SVG and the exact sanitized markup returned by the WordPress output path.
- Inventory svg, path, polygon, stroke, fill, group, mask, gradient, style, class, and event attributes in every icon.
- Compare the Icon block, REST retrieval, saved content, wp_get_icon(), cached HTML, dark mode, and high-contrast output.
- Check whether theme CSS sets fill, color, width, height, display, or currentColor on every SVG in a broad selector.
- Verify decorative icons stay hidden from assistive technology and meaningful icons receive an accurate accessible label.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Stroke-only source | Outlined 24px icon | Converted supported path keeps shape |
| Outer fill | Fill only on svg element | Scoped CSS or shape fill is intentional |
| Unsupported markup | g, circle, mask, style | Removed without unsafe bypass |
| Output parity | Block, REST, PHP, cache | Same accepted geometry and label |
Decision rule
Ship the icon only when the sanitized output preserves the intended silhouette, color is controlled by a narrow rule, every output path agrees, and no global sanitization exception is required.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Record the original and sanitized SVG for one failing icon.
- Replace unsupported drawing features with the smallest supported path or polygon geometry.
- Move color behavior into a narrow class that targets only the registered icon.
- Retest block, REST, PHP, cache, contrast, zoom, and assistive-technology behavior.
- Ship the corrected asset with a visual regression fixture and an owned fallback.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Record the original and sanitized SVG for one failing icon. | Save the original SVG and the exact sanitized markup returned by the WordPress output path. | The returned SVG contains only expected allowed elements and attributes. |
| Replace unsupported drawing features with the smallest supported path or polygon geometry. | Inventory svg, path, polygon, stroke, fill, group, mask, gradient, style, class, and event attributes in every icon. | Light, dark, forced-color, zoom, and mobile checks preserve meaning. |
| Move color behavior into a narrow class that targets only the registered icon. | Compare the Icon block, REST retrieval, saved content, wp_get_icon(), cached HTML, dark mode, and high-contrast output. | Block, REST, PHP, and cached output display the same icon. |
| Retest block, REST, PHP, cache, contrast, zoom, and assistive-technology behavior. | Check whether theme CSS sets fill, color, width, height, display, or currentColor on every SVG in a broad selector. | Decorative and meaningful icon labels match their accessibility purpose. |
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
# Inspect SVG features before registration
rg '<(g|circle|rect|mask|defs|style)|stroke=|fill=' assets/icons
# Compare returned markup
wp eval "echo wp_get_icon( 'acme/alert', array( 'class' => 'acme-alert' ) );"
.accepted-icon path { fill: currentColor; }
Production verification checklist
- The returned SVG contains only expected allowed elements and attributes.
- Light, dark, forced-color, zoom, and mobile checks preserve meaning.
- Block, REST, PHP, and cached output display the same icon.
- Decorative and meaningful icon labels match their accessibility purpose.
Why this usually happens
- The source depends on stroke, but the current API strips that attribute.
- A designer export contains groups, masks, gradients, or style blocks outside the allowlist.
- A broad theme selector overrides the surviving fill with black or currentColor.
- The editor preview and server render are tested with different markup or caches.
Field notes
- Use synthetic IDs and examples that can be traced from the first request or interaction to the final record.
- Keep a before and after result for every changed setting, package, selector, route, or deployed version.
- Separate user-visible success from internal success so a green interface cannot hide a failed request or inaccessible control.
- Review the evidence after caches, queues, browser history, and scheduled work have had time to settle.
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, settings, stable fixture IDs, and a reproducible baseline.
- Treating one successful screen as proof that keyboard access, APIs, caches, jobs, reports, analytics, and downstream records agree.
- Testing only an administrator session instead of the devices, roles, networks, locales, and failure branches customers use.
- Closing the work without a named owner, rollback point, observation window, and contextual incoming link from an established guide.
What to tell the client or owner
Give the site owner the affected versions, exact synthetic fixture, UTC timeline, before and after evidence, cause class, decision, rollback point, unresolved risks, and next review date. State which measurements prove success and which observation window remains open.
Questions teams ask during testing
Can this be tested on production?
Use production for read-only checks and one narrow synthetic fixture that cannot charge a card, send customer email, expose personal data, or change inventory. Run upgrades, package changes, cache changes, and destructive repairs on staging first.
What evidence should the test report keep?
Keep exact versions, UTC timestamps, stable synthetic IDs, expected and actual results, screenshots or response excerpts, the decision owner, rollback point, and final verification. Redact credentials, tokens, customer data, private addresses, and infrastructure details.
How long should the observation window stay open?
Keep it open long enough to include at least one cache cycle, scheduled job cycle, and representative traffic period. For release changes, include logged-in and logged-out use plus the first real operational handoff.
When is the task complete?
Complete it when the primary user path passes, downstream records reconcile, failure branches are understood, monitoring is active, and an established owner page links to this guide in context.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, repair a WordPress 7.1 icon integration.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references