WordPress 7.1 Icons API: The v15 Breaking Change You Missed

Icons are the kind of thing you stop noticing after the third year in this job. A pencil for edit, a trash can for delete, a gear for settings — you register them once, you write a bit of CSS to tint them, and you move on to work that matters. And then a package version bumps, the tint stops applying, and you spend a Monday morning wondering why every icon in the plugin you shipped last year suddenly went black.

WordPress 7.1 has a version bump like that hidden inside it. Not a flashy feature, not something that gets a headline at WordCamp US next month — just a quiet shift in @wordpress/icons and a small but meaningful expansion of the server-side Icons API. If you build blocks, if you build admin screens, if you ship any plugin that draws an SVG anywhere, this is worth thirty minutes on staging before August 19.

I have watched this pattern before. WordPress 5.9 quietly shifted how block styles inherited color. Half our client codebases handled it well. The other half had exactly one line of CSS written in 2019 by someone who is no longer with the company, and that one line kept a broken thing looking correct until the day it did not. The 7.1 icons work is going to expose the same kind of debt.

What is actually new

Two moving parts. First, the JavaScript package. All 330 icons in @wordpress/icons v15 now ship with fill="currentColor" baked into the SVG. That is a breaking change for any consumer that was tinting icons with the CSS fill property. The fix is one line — style the icon with color instead of fill — but you have to find every place you did it the old way. The change is called out in the July 2026 developer roundup on developer.wordpress.org.

Second, the server-side Icons API that shipped in WordPress 7.0 is getting a proper public surface. The tracking issue Gutenberg #75715 by Aki Hamano lays out the plan: register_icon() and unregister_icon() as public functions, a companion wp_register_icon_collection() / wp_unregister_icon_collection() pair, a new WP_Icon_Collections_Registry, and a /wp/v2/icon-collections REST endpoint so the editor can list what is available without hardcoding names.

The registry gets stricter on the way in. Custom icons must now be registered under a {namespace/icon-name} format — no more bare slugs colliding with core. Search inside WP_Icons_Registry also expands from a name-only lookup to include label and keyword fields, which is what makes the icon picker in the editor actually useful when your icon is called brand-logo-mono but the editor has “logo” in the search box.

Two smaller cleanups on the same track. The registry array key filePath becomes file_path — snake_case, the way WordPress is meant to look — and the built-in Icon block gains flip and rotate controls and honors block.json default icons. The fill="currentColor" flip on the JS package is not a coincidence — it is the pattern that makes registered icons and Icon block instances behave consistently whether they land in an admin panel, a block toolbar, or a rendered post.

None of this is speculative. Beta 1 shipped on July 15 per wordpress.org/news and the API surface for the August 19 GA is what is in Beta 1 today. The 7.1 release page confirms the schedule (Beta 2 July 22, Beta 3 July 29, RC 1 August 5).

Why it matters for WordPress and WooCommerce people

If you never touched @wordpress/icons directly, you still probably ship it. Any block plugin built from @wordpress/create-block in the last three years pulls the package in as a dependency, and every SidebarPanel or Toolbar built for the block editor almost certainly imports at least a couple of icons from it. So a breaking change on the package hits far more codebases than the change note implies.

The failure mode is not dramatic. Nothing throws. The plugin loads. Icons render. They just render in the wrong color — usually plain black on a light background, or invisible white on a dark one — because the CSS rule that used to hit fill is now hitting nothing. On a WooCommerce admin screen with a dark toolbar, that reads as a bug the merchant reports on August 20.

The public registration functions matter for a different reason. Until 7.1, if you wanted to register a custom brand icon and have it discoverable by the Icon block picker and the Navigation block, you were either poking at a protected class method or shipping your own registry. From 7.1 GA onward there is one canonical way, and the /wp/v2/icon-collections endpoint means an editor built in React or a future AI agent can enumerate what exists on a site without a hardcoded list.

WooCommerce framing: WooCommerce 11.0 lands July 28. Your Woo store on 7.0.2 stable will not see any of the icons work until you update WordPress core to 7.1 — which per our 11.0 checklist should be a separate change window from the Woo upgrade. Do not stack them.

What I would do (or not do) about it

Four passes this week, in order.

• Grep every plugin and theme in the estate for CSS selectors that touch svg { fill: ... }, .some-icon { fill: ... }, or any styled-components rule setting fill on icon components. Every hit is a candidate. Change to color, verify the icon still tints correctly, ship.
• Grep for direct WP_Icons_Registry::register() calls, custom icon registration shims, and any array key called filePath in icon-related code. Flip filePath to file_path. If you were poking the protected method, switch to register_icon() — and add a version guard (if ( function_exists( 'register_icon' ) )) so 7.0 sites do not fatal.
• Audit custom icon slugs. If you registered logo or brand or arrow-right as a bare name, 7.1 will refuse it. Prefix with a namespace you own — acme/logo, acme/brand. The rename is a data change too if you stored the slug in postmeta or options, so plan the migration path.
• Regression test on Beta 1 or Beta 2. Not on production. On a Playground blueprint or a staging clone. Open every admin screen in your plugin, every block in the inserter, every settings page — with both a light and a dark admin color scheme active. Icons that look wrong in either scheme are the ones you need to fix.

What I would not do: patch the icons back to explicit fill attributes with a filter. Two weeks of relief, then technical debt with no upgrade path when the next Gutenberg cycle refines the pattern further. Fix the CSS, not the framework.

I would also not treat /wp/v2/icon-collections as production-ready for building tooling on top of yet. Wait one release cycle. The endpoint shape is stable enough for internal editor use in 7.1 GA, but external consumers should let the surface settle before writing dashboards against it.

Icons are boring on purpose. That is the compliment. When the underlying API gets a little less clever and a little more consistent, the plugins that survive the next five years of WordPress are the ones that lean into it now — not the ones patching around it in October.