Icons: Add a core-admin collection for the admin interface

[t-hamano]

Note

This PR depends on #83277, which needs to move forward first. #83277 has been merged ✅

• Related to Admin: replace dashicons in admin bar and sidebar with @wordpress/icons wordpress-develop#12270
• Alternative to Icons: Add a reserved _builtin collection #83012

What?

Adds a core-admin icon collection for the dashboard, alongside the default core collection.

Why?

WordPress/wordpress-develop#12270 extends the menu API to accept a name from the icons registry, so that the admin bar and the admin menu can render SVG icons in place of dashicons. The icons it references belong to the core collection.

That makes the dashboard icons collateral damage of something a consumer may reasonably do. Code like the following, meant only to keep the core icon set out of the Icon block, would wipe out every SVG icon in the admin bar and the admin menu as well:

add_action( 'init', function () {
	wp_unregister_icon_collection( 'core' );
}, 20 );

Following the discussion, the conclusion was that the admin interface needs a collection separate from core.

How?

• A new admin property in the icons manifest marks the icons the admin interface renders. core-admin and its icons are registered by default from that property, and this is the collection the admin bar and the admin menu are meant to use.
• An icon marked admin is registered in core-admin in addition to core. It is always non-public there.
• core-admin is not protected in any way the other collections are not. Keeping the logic and the rules as simple as possible was preferred over guarding it.
• Since every icon in core-admin is non-public, the collection contributes nothing to the icons REST API or to the Icon block. The collection itself is still exposed, so the Icon block now leaves out a collection that holds no icon at all, the same way the site editor's Patterns page hides empty pattern categories.

Testing Instructions

Icon block

1. Add an Icon block and open the icon picker.
2. Confirm that there is no WordPress Admin collection in the sidebar.
3. Watch the Network tab while switching collections. There should be a single request for icons, made when the modal opens.

REST API

Run the following in the browser console on any wp-admin screen that loads wp-api-fetch, such as the post editor.

The collections should include core-admin:

await wp.apiFetch( { path: '/wp/v2/icon-collections' } );

That collection should hold zero icons:

( await wp.apiFetch( { path: '/wp/v2/icons/core-admin' } ) ).length;

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: code generation and testing, with my supervision.

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: 0 B

Total Size: 8.21 MB

_{6025ffa Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	b5a2e0d	trunk	% Change
timeToFirstByte	57.85 ms +11.84% -2.85%	56.4 ms +7.36% -3.46%	2.57%
largestContentfulPaint	98 ms +6.12% -6.12%	90 ms +6.67% -2.22%	8.89%
lcpMinusTtfb	36.7 ms +17.3% -9.13%	33.45 ms +3.89% -3.89%	9.72%
wpBeforeTemplate	28.51 ms +17.19% -1.26%	28.05 ms +13.23% -1.6%	1.64%
wpTemplate	25.13 ms +2.9% -5.85%	23.95 ms +2.67% -3.05%	4.93%
wpTotal	54.27 ms +11.13% -3.11%	52.36 ms +8.23% -2.35%	3.65%
wpMemoryUsage	7.61 MB +0% -0%	7.55 MB +0% -0%	0.74%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	b5a2e0d	trunk	% Change
timeToFirstByte	46.8 ms +5.02% -2.35%	47.55 ms +6.62% -3.26%	-1.58%
largestContentfulPaint	102 ms +5.88% -1.96%	100 ms +4% -0%	2%
lcpMinusTtfb	54.65 ms +7.87% -0.64%	53.75 ms +1.12% -2.88%	1.67%
wpBeforeTemplate	25.65 ms +2.46% -0.7%	26.3 ms +9.05% -3.12%	-2.47%
wpTemplate	17.84 ms +6.11% -3.25%	17.76 ms +1.86% -2.2%	0.45%
wpTotal	43.79 ms +5.14% -2.35%	44.35 ms +7.28% -2.86%	-1.26%
wpMemoryUsage	6.22 MB +0% -0%	6.17 MB +0% -0%	0.85%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	b5a2e0d	trunk	% Change
mediaProcessingJpeg	397.7 ms +2.09% -0.16%	395.48 ms +0.63% -0.4%	0.56%
mediaProcessingAvif	6049.09 ms +0.17% -0.23%	6035.43 ms +0.17% -0.04%	0.23%
mediaProcessingJpegToAvif	4186.59 ms +0.19% -0.27%	4167.97 ms +0.07% -0.16%	0.45%

media-upload

Metric	b5a2e0d	trunk	% Change
jpegUploadProcessing	1437.25 ms +34.93% -0.97%	1413.39 ms +1.38% -0.43%	1.69%
pngUploadProcessing	186.34 ms +16.3% -6.78%	204.17 ms +5.84% -9.15%	-8.73%
largeJpegUploadProcessing	1400.98 ms +1.13% -0.24%	1415.13 ms +0.43% -0.62%	-1%
multipleImageUploadProcessing	1530.34 ms +1.01% -0.73%	1588.91 ms +8.95% -2.97%	-3.69%

post-editor

Metric	b5a2e0d	trunk	% Change
serverResponse	517.63 ms +1.67% -5.59%	502.92 ms +2.58% -6.42%	2.92%
firstPaint	229.39 ms +4.8% -12.9%	238.38 ms +12.19% -19.56%	-3.77%
domContentLoaded	1113.56 ms +2.62% -1.65%	1082.81 ms +2.3% -3.3%	2.84%
loaded	1114.94 ms +2.6% -1.66%	1083.97 ms +2.32% -3.3%	2.86%
firstContentfulPaint	460.7 ms +2.21% -3.93%	447.86 ms +4.13% -1.83%	2.87%
firstBlock	3300.01 ms +1.07% -1.24%	3200.78 ms +0.98% -1.13%	3.1%
type	21.76 ms +4.92% -3.22%	19.05 ms +5.04% -5.67%	14.23%
typeWithoutInspector	19.54 ms +2.3% -1.54%	18.26 ms +4.76% -6.3%	7.01%
typeWithTopToolbar	25.89 ms +4.83% -12.67%	23.43 ms +5.21% -4.95%	10.5%
typeContainer	9.02 ms +12.53% -4.21%	9.52 ms +7.14% -13.66%	-5.25%
focus	72.8 ms +7.53% -2.82%	69.23 ms +2.79% -6.54%	5.16%
firstFocus	209.16 ms +0% -0%	199.81 ms +0% -0%	4.68%
selectAll	506.38 ms +4.04% -1.2%	522 ms +5.67% -1.32%	-2.99%
listViewOpen	61.69 ms +4.93% -11.51%	77.32 ms +8.19% -11.3%	-20.21%
inserterOpen	23.34 ms +11.14% -14.95%	22.81 ms +14.03% -6.01%	2.32%
inserterHover	2.66 ms +6.39% -4.51%	3.11 ms +16.08% -10.61%	-14.47%
inserterSearch	7.94 ms +10.96% -5.42%	8.18 ms +5.01% -13.81%	-2.93%
loadPatterns	610.49 ms +3.84% -1.22%	643.58 ms +3.72% -5.99%	-5.14%
wpTotal	507.52 ms +1.82% -5.72%	493.12 ms +2.59% -6.48%	2.92%
wpMemoryUsage	13.14 MB +0% -0%	13.09 MB +0% -0%	0.41%
wpDbQueries	53 +1.89% -0%	54 +0% -1.85%	-1.85%

site-editor

Metric	b5a2e0d	trunk	% Change
serverResponse	516.43 ms +3.45% -3.59%	501.38 ms +3.76% -5.43%	3%
firstPaint	241.46 ms +17.48% -2.63%	252.57 ms +15.06% -6.57%	-4.4%
domContentLoaded	1164.92 ms +2.22% -2.7%	1149.32 ms +1.21% -2.1%	1.36%
loaded	1166.26 ms +2.23% -2.69%	1150.6 ms +1.2% -2.11%	1.36%
firstContentfulPaint	460.38 ms +2.25% -2.29%	451.22 ms +3.03% -2.22%	2.03%
firstBlock	4255.89 ms +0.63% -1.89%	4189.42 ms +0.48% -1.4%	1.59%
type	19.52 ms +8.91% -4.15%	20.66 ms +6.2% -4.55%	-5.52%
navigate	121.53 ms +7.81% -6.43%	121.1 ms +8.03% -13.98%	0.36%
loadPatterns	1332.69 ms +1.13% -7.66%	1401.64 ms +14.62% -11.43%	-4.92%
loadPages	1065.02 ms +1.22% -2.14%	1076.15 ms +7.33% -1.54%	-1.03%
wpTotal	506.67 ms +3.43% -3.65%	491.74 ms +3.9% -5.49%	3.04%
wpMemoryUsage	12.11 MB +0% -0%	12.05 MB +0% -0%	0.45%
wpDbQueries	43 +2.33% -0%	43.5 +1.15% -1.15%	-1.15%

_{6025ffa Run}

🏁 Flaky tests

Show the failures

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

should cut and paste individual blocks with collapsed selection in /test/e2e/specs/editor/various/copy-cut-paste.spec.js, passed after 1 failed attempt.

Error: expect(string).toMatchSnapshot(expected) failed

  @@ -1,3 +1,3 @@
   <!-- wp:paragraph -->
  -<p>2Cut - collapsed selection</p>
  +<p>2</p>
   <!-- /wp:paragraph -->


    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/copy-cut-paste.spec.js:45:49

three users concurrently edit a large post with diverse blocks in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts, passed after 1 failed attempt.

TimeoutError: locator.waitFor: Timeout 17500ms exceeded.
Call log:
  - waiting for getByRole('button', { name: /Collaborators list/ }) to be visible

    at map (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:193:7)
    at CollaborationUtils.waitForMutualDiscovery (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:188:10)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:416:28

_{6025ffa Run}

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: fushar <fushar@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[fushar]

Thanks for this! The idea of a separate admin-only, private collection is looking more solid now.

I think this PR is good as-is. However, I contemplated a bit and would like to propose an idea to simplify the logic even further:

• Revert the public: false ternary boolean from icon-level (the feature is not released yet in any GB release).
• Add the concept to the collection level instead, so wp_register_icon_collection() accepts public => false.
• The REST API simply does not return non-public collections (and their icons).

The benefits are the following:

• public is now really a boolean state, not ternary. It's simpler concept.
• We don't need to update the logic in packages/block-library/src/icon/components/custom-inserter/index.jsx as we do in this PR, which is done to hide the collection.
• Related to the above, all consumers of the /icon-collections do not need to filter out empty collections themselves.
• I think it's simpler mental model overall. If plugins want to have server-only icons, add them to a separate private collection.

Thoughts? @t-hamano @tyxla @mcsf

[t-hamano]

@fushar Thanks for the review!

• Revert the public: false ternary boolean from icon-level (the feature is not released yet in any GB release).
• Add the concept to the collection level instead, so wp_register_icon_collection() accepts public => false.
• The REST API simply does not return non-public collections (and their icons).

I think this is a great idea. The original reason we needed the public property was to apply the core icon set to the admin bar or sidebar without exposing the icons to the icon block. Is my understanding correct?

Since we are now introducing the core-admin collection separately from the core collection, the public property might no longer be necessary. My only concern is that consumers will lose the flexibility to distinguish between public and non-public icons within a single icon set.

Gutenberg 24.1 RC is scheduled to be released this Wednesday, the day after tomorrow, so reverting the public property by then should be fine.

[fushar]

The original reason we needed the public property was to apply the core icon set to the admin bar or sidebar without exposing the icons to the icon block. Is my understanding correct?

Yes, this is correct! The dashicons -> wp/icons migration was the entire reason.

My only concern is that consumers will lose the flexibility to distinguish between public and non-public icons within a single icon set.

I think we can easily reintroduce this mechanism if necessary in the future if needed. Right now, with private collection, I don't see we need that kind of icon-level flexibility. 🤔

[mcsf]

Seems to be on the right track

[mcsf]

Also, I'm on board with @fushar's suggestion :)

[t-hamano]

• phpunit/class-wp-rest-icon-controller-test.php, class-wp-icon-test.php and render-block-icon-test.php: the set_up checks assume there is only one default collection. If a test unregisters core, the next test will try to register core-admin again and fail.

Fixed in a6b49b6

• lib/class-wp-icons-registry-gutenberg.php: the replay only skips core/ icons. I think it should skip core-admin/ too, since Gutenberg registers those from its own manifest.

Fixed in 4f91c5e

[t-hamano]

@fushar @tyxla, thanks for the review!

One of the reasons this PR was confusing is probably that I added an admin property alongside the public property in the manifest file to represent non-public icons. In other words, it looks like this:

public	admin	Ships to Core?	Registered in
omitted	omitted	No	—
true	omitted	Yes	core
omitted	true	Yes	core-admin
true	true	Yes	core, core-admin

To eliminate this confusion, I removed the public and admin fields and introduced the collections field instead. It looks like this:

collections	Ships to Core?	Registered in
omitted	No	—
[ "core" ]	Yes	core
[ "core-admin" ]	Yes	core-admin
[ "core", "core-admin" ]	Yes	core, core-admin

I would appreciate it if you could share your thoughts on this.

[fushar]

Sorry it took me a bit to fix my local setup to be able to run WP and GB locally. Our PRs now work together 👍

Now reviewing the code...

[tyxla]

One thing to keep in mind is that Storybook icon library (storybook/stories/icons/library.story.tsx) still uses public - maybe we want to check collections instead?

[fushar]

To eliminate this confusion, I removed the public and admin fields and introduced the collections field instead. It looks like this:

I like it! Now I don't need to think what public and admin mean when looking at manifest.json file 🙂 it's self-explanatory now.

[fushar]

@fushar, It might be better to move forward with #83338 first and reconsider the list of SVG icons to be used in the admin bar and sidebar.

I added a comment in that PR, suggesting that we just update the existing icons. 🙈 cc: @jasmussen

In any case, I think we can move forward with this PR, and update the core-admin collection later if really necessary (in RC version).

[fushar]

Other than the Storybook issue that Marin pointed out above, I think this PR is in a good shape, and I've tested it. Giving my thumbs-up 👍 thanks for this.

[jasmussen]

Noting that the icons are now renamed instead of new ones in #83338.

[t-hamano]

I updated Storybook so that icons can now be filtered by collection.

I will merge this PR so it can be included in today's Gutenberg 24.1 RC release. As for Storybook, we can make further improvements in a follow-up if needed.

icon-storybook.mp4

[fushar]

Thanks, tested the Storybook locally and it looks good. Maybe we could add an indication that core-admin is only available via wp_get_icon(), but it can be an enhancement later if needed. 👍