Every WordPress 7.1 icon belongs to a collection, and the collection slug becomes the namespace in names such as acme-icons/alert. Generic slugs, duplicate icon names, late registration, untranslated labels, and unconditional unregister calls can make one extension hide another collection or leave patterns pointing at an icon that no longer exists.
Use this for product teams shipping icon libraries in plugins, themes, must-use plugins, multisite networks, reusable patterns, and client-specific design systems.
Quick answer
Prefix the collection with a stable product or vendor identifier, register it on init before its icons, and treat the slug as a public compatibility contract. Keep the slug language-neutral while translating the label and description with the extension text domain. Capture each registration return value and development notice, then test duplicate plugin activation, theme switching, multisite network activation, locale switching, pattern insertion, and clean removal. Do not rename a live collection without a content migration plan.
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 |
|---|
| Duplicate collection | Two plugins register icons | Second failure is visible and owned |
| Locale switch | English and Spanish admin | Labels translate, slug stays fixed |
| Theme switch | Pattern contains registered icon | Known fallback or preserved icon |
| Removal | Unregister after registration | Collection and children leave cleanly |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Choose a prefixed, language-neutral collection slug and document its owner. | Inventory every wp_register_icon_collection(), wp_register_icon(), and wp_unregister_icon_collection() call across plugins and themes. | No installed plugin or theme claims the same collection or icon name. |
| Register the collection before icons on init and log failed return values during testing. | Confirm collection and icon slugs satisfy the lowercase naming rules and include a durable vendor prefix. | Translated UI labels change while content identifiers remain stable. |
| Translate labels and descriptions while preserving names stored in content. | Load two extensions with intentionally overlapping generic names and record return values plus development notices. | Patterns and templates resolve after activation-order and theme-switch tests. |
| Add migration or fallback handling before a collection or icon rename. | Switch the user and site locale while verifying translated labels, descriptions, search, and stored icon names. | Unregister behavior is scoped, logged, and reversible. |
What to check first
- Inventory every wp_register_icon_collection(), wp_register_icon(), and wp_unregister_icon_collection() call across plugins and themes.
- Confirm collection and icon slugs satisfy the lowercase naming rules and include a durable vendor prefix.
- Load two extensions with intentionally overlapping generic names and record return values plus development notices.
- Switch the user and site locale while verifying translated labels, descriptions, search, and stored icon names.
- Search post content, patterns, templates, and options for collection/icon references before renaming or removing a collection.
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.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_action( 'init', function () {
$ok = wp_register_icon_collection( 'acme-commerce', array(
'label' => __( 'Commerce Icons', 'acme-commerce' ),
'description' => __( 'Icons for Acme commerce blocks.', 'acme-commerce' ),
) );
error_log( 'icon_collection=' . ( $ok ? 'registered' : 'failed' ) );
}, 10 );
Why this usually happens
- A generic collection slug such as icons or brand is already claimed by another extension.
- The collection is registered after icons or only in an admin-only hook.
- A translated string is used as the stored slug, so the identifier changes by locale.
- A deactivation routine removes a collection that another component expects.
Decision rule
Approve the collection when its namespace is unique, stored names remain stable across locales, duplicate registration fails visibly, and removal cannot strand published content without a fallback.
Production verification checklist
- No installed plugin or theme claims the same collection or icon name.
- Translated UI labels change while content identifiers remain stable.
- Patterns and templates resolve after activation-order and theme-switch tests.
- Unregister behavior is scoped, logged, and reversible.
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.
- Choose a prefixed, language-neutral collection slug and document its owner.
- Register the collection before icons on init and log failed return values during testing.
- Translate labels and descriptions while preserving names stored in content.
- Add migration or fallback handling before a collection or icon rename.
- Test activation order, multisite, locale, theme switches, patterns, and removal.
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.
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.
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.
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, review a WordPress icon collection.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references