Add Icon APIs: registry and /wp/v2/icons endpoint by mcsf · Pull Request #10909 · WordPress/wordpress-develop

mcsf · 2026-02-12T12:38:09Z

Companion PR to Gutenberg's WordPress/gutenberg#72215 and WordPress/gutenberg#74943

Builds on #10795

Trac ticket: https://core.trac.wordpress.org/ticket/64651

github-actions · 2026-02-12T12:57:57Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

fabiankaegy · 2026-02-12T15:40:00Z

src/wp-includes/class-wp-icons-registry.php

+	 * }
+	 * @return bool True if the icon was registered with success and false otherwise.
+	 */
+	private function register( $icon_name, $icon_properties ) {


I do not think we should merge in this API without a public method for registering icons.

The icon library we are shipping with Core is the gutenberg icons. Those icons were never meant to be frontend design icons. They are editor interface icons.

From my POV there is very little utility to the icon block in core without the ability to register custom icons.

I understand where you're coming from, but I'd argue that the Icon block is already useful in its initial form, having access to 321 core icons.

Though @wordpress/icons was developed to support the needs of the editor, IMO it's fair to say that the icon set can accommodate more uses. Folks like @jasmussen, @jameskoster and others have been iterating on those icons and are involved in the making of the Icon block, which I take as a sign that, though imperfect, the icon set has evolved beyond its original purpose.

Keeping the Icons registry closed was a way to conserve some more room for adjustments, as the icon block itself gets adopted. It should be understood as an intermediate step, so that we can confidently expand the scope of the registry in 7.1 (third-party registration, but possibly also categories, etc.).

Thanks for the ping. As happens more often than I like, I find myself agreeing with both ends of the spectrum.

On the one hand, let's be honest that the utility of this first iteration is limited: there are many inline contexts where I would like to use icons, but can't. There's just that one set, and although there are many nice icons there, the majority of them were designed for blocks, or WordPress specific features.

On the other hand, while this effort is also about adding a block that lets you intiutively create decorative bullets and expanded patterns, it's also a mammoth infrastructure effort, to bring SVG support to WordPress, to wrap it in a UI that we can grow, expand, and iterate. Most of this work may not be quite as exciting and immediately useful, but wait til you see what we can do with it. We're building a mountain, moving dirt to one place, and eventually what we build will be visible on the horison.

In saying that, I'm validating every aspect of Fabian's point. I think this is especially important if we were to land in 7.0 and market this new feature: we should be very honest that this is a small first step, not the end-state. There are shortcomings: SVG support is the big deal. But with that, I'm also validating Miguel's instinct: this ground work is critical, and there's no better test crucible than to ship this in a major release, so we can work out the inevitable issues.

None of this is strongly felt. There's always another release. But it's a soft appeal: I'd rather take 4 deliberate, but small steps, than make one big jump and risk landing in the wrong place.

After talking with Joen, I also opened WordPress/gutenberg#75526 to distinguish "front-end-ready" icons from internal ones.

Keeping the Icons registry closed was a way to conserve some more room for adjustments, as the icon block itself gets adopted. It should be understood as an intermediate step, so that we can confidently expand the scope of the registry in 7.1 (third-party registration, but possibly also categories, etc.).

I also agree with this approach. To get attention and move this PR forward, we might want to submit a core ticket first.

-> https://core.trac.wordpress.org/ticket/64651

I think the incremental approach @mcsf is suggesting is a good call. Shipping the registry and REST endpoint now gives an initial foundation to build on, and keeping register() private for this first iteration is a good way to leave room for refinement before committing to a public API surface.
I think merging this PR (and the icon block) would allow some icon block testing before committing to how third parties can add additional icons. We would get a better sense of how the block is used, and the icons package already offers some icons that can be useful.

github-actions · 2026-02-16T17:00:37Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props mcsf, wildworks, fabiankaegy, joen, jorgefilipecosta, ntsekouras.

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

ntsekouras

I definitely get @fabiankaegy's point, but I think we should ship this essential infrastructure and not rush the public API for registration until the next WP version. It will give some exposure to the Icon block and it will help us move forward more confidently.

Will it be as useful as it can be at first? No. Will it be useful though at all? I strongly believe yes, as the public icons set includes quite a few 'util' icons that can serve many use cases.

As @jasmussen says we shouldn't market this feature as something more than it is, but the infrastructure work shouldn't be blocked.

t-hamano

In WordPress/gutenberg#75526, we marked the icons that should be made public as 'public' => true. However, in this PR, we're not checking that field, so all icons not marked as public will be included and may be unintentionally made public. Is this correct?

If so, one of the following approaches may be necessary:

Copy all icons, but check whether the public field is true in the icon registry.
When copying icons, if the public field is not true, do not copy the icon. Additionally, remove icons not marked as 'public' => true from the manifest.php file.

Perhaps the latter approach is ideal if we don't want to ship internal icons entirely into core, but it may be a bit more complicated. What do you think?

t-hamano · 2026-02-17T15:26:44Z

Copy all icons, but check whether the public field is true in the icon registry.

When copying icons, if the public field is not true, do not copy the icon. Additionally, remove icons not marked as 'public' => true from the manifest.php file.

Perhaps the latter approach is ideal if we don't want to ship internal icons entirely into core, but it may be a bit more complicated. What do you think?

@mcsf Since we're getting close to the Beta 1 release and the former approach is simpler, I’ve committed 970944b using that approach. I’d appreciate your thoughts.

mcsf · 2026-02-17T16:10:36Z

@mcsf Since we're getting close to the Beta 1 release and the former approach is simpler, I’ve committed 970944b using that approach. I’d appreciate your thoughts.

Sorry, I thought I had submitted a reply but apparently not. Yes, that's what I would prefer!

t-hamano · 2026-02-17T16:53:02Z

src/wp-includes/class-wp-icons-registry.php

+			if ( ! ( $icon_data['public'] ?? false ) ) {
+				continue;
+			}


I think this code caused the unit test to fail.

There was 1 error: 1) Tests_REST_WpRestIconsController::test_prepare_item Undefined offset: 0 /var/www/tests/phpunit/tests/icons/wpRestIconsController.php:114 phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106 /var/www/vendor/bin/phpunit:118

GitHub Action Example: https://github.com/WordPress/wordpress-develop/actions/runs/22104294772/job/63882418252?pr=10909

I think the reason is that the Gutenberg commit hash defined in WordPress core does not yet have an icon marked as public->true in manifest.php. I think there are two ways to solve this. What do you think?

Skip unit testsfor now, and restore unit tests after Beta1 is released.

Register custom icons for unit tests to avoid dependency on manifest.php.

t-hamano · 2026-02-18T08:09:05Z

Update:

7b941e4: I skipped the failing tests because there are no public icons in manifest.php yet. Once the Gutenberg commit hash is updated, we'll be able to re-enable the skipped tests. At first, I thought about registering a mock icon, but after reading this comment, I realized that that approach wasn't the right one.
15a38c3: I added a ticket tag.

t-hamano · 2026-02-18T08:10:05Z

tests/phpunit/tests/icons/wpRestIconsController.php

+
+		// All returned icons should contain "arrow" in their name (case insensitive)
+		foreach ( $data as $icon ) {
+			$this->assertStringContainsStringIgnoringCase( 'arrow', $icon['name'] );


Note that this test isn't actually running at all, because there are no public icons.

mcsf · 2026-02-18T10:03:41Z

7b941e4: I skipped the failing tests because there are no public icons in manifest.php yet. Once the Gutenberg commit hash is updated, we'll be able to re-enable the skipped tests. At first, I thought about registering a mock icon, but after reading this comment, I realized that that approach wasn't the right one.

Awesome, thanks. For the record, I just tested building WordPress with an updated Gutenberg ref, removed the tests' skip instructions, and I can confirm that the tests pass with the right manifest. 👍

mcsf · 2026-02-18T10:04:12Z

I think we should be good to go. What else is missing for this initial commit?

t-hamano

It looks almost good, but I overlooked an important point: the text domain of the icon in the manifest.php file is gutenberg, so it will not be translatable in core. Would it be difficult to remove this text domain during the build process?

t-hamano · 2026-02-18T10:12:10Z

src/wp-includes/class-wp-icons-registry.php

+ */
+
+/**
+ * FIXME


Nit: Can we remove the FIXME and provide a class summary here?

t-hamano · 2026-02-18T10:14:22Z

src/wp-includes/rest-api/endpoints/class-wp-rest-icons-controller.php

+			array(
+				'args'   => array(
+					'name' => array(
+						'description' => __( 'Icon name.', 'gutenberg' ),


Oops, I missed this. Let's remove all gutenberg text domains from this PR.

fabiankaegy requested changes Feb 12, 2026

View reviewed changes

mcsf force-pushed the add/icons-apis branch 2 times, most recently from 9aaf4d0 to 06d0995 Compare February 12, 2026 18:57

t-hamano mentioned this pull request Feb 14, 2026

Build: Copy Icons manifest file from Gutenberg #10795

Closed

github-actions bot mentioned this pull request Feb 16, 2026

PHP backports for WP 7.0 WordPress/gutenberg#74043

Open

mcsf marked this pull request as ready for review February 16, 2026 17:00

mcsf added 7 commits February 16, 2026 17:04

Build: Copy Icons manifest file from Gutenberg

615e544

Copy icon SVGs to wp-includes/icons/library

f7d5a91

Always assert glob not empty

3bc226a

Prefer glob; fs.globSync requires node >= 22

2a04dd6

Add Icon APIs: registry and /wp/v2/icons endpoint

a0ab11e

Update tests/qunit/fixtures/wp-api-generated.js

5cc4fdc

Add Tests_REST_WpRestIconsController

8446d5e

mcsf force-pushed the add/icons-apis branch from 3c91698 to 8446d5e Compare February 16, 2026 17:04

ntsekouras approved these changes Feb 17, 2026

View reviewed changes

t-hamano reviewed Feb 17, 2026

View reviewed changes

Don't register no-public icons

970944b

t-hamano reviewed Feb 17, 2026

View reviewed changes

t-hamano and others added 4 commits February 18, 2026 16:28

Merge branch 'trunk' into add/icons-apis

7962d77

Temporarily skip failing tests

7b941e4

Add ticket tag

15a38c3

Merge branch 'trunk' into add/icons-apis

9ab1f42

t-hamano reviewed Feb 18, 2026

View reviewed changes

+               */
+              /**
+               * FIXME

Conversation

mcsf commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 12, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ntsekouras left a comment

Choose a reason for hiding this comment

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Feb 17, 2026

Uh oh!

mcsf commented Feb 17, 2026

Uh oh!

t-hamano Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Feb 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcsf commented Feb 18, 2026

Uh oh!

mcsf commented Feb 18, 2026

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mcsf commented Feb 12, 2026 •

edited

Loading

github-actions bot commented Feb 16, 2026 •

edited

Loading

t-hamano Feb 17, 2026 •

edited

Loading