Icons: Ship all SVG icons to WordPress core

[t-hamano]

• Depends on Icons: Use snake_case file_path key in icon registry #79100
• See Icons: Add PHP method(s) for rendering inline SVG icons from the registry #78332 (comment)

What?

Previously, only icons marked as "public" within the icons package were available in the icon registry. This has been achieved through the following mechanism:

• In manifest.json, add the field "public": true to the icons we want to make public.
• When generating manifest.php from manifest.json, only icons with "public": true defined are included.
• Icons are registered in the icon registry based on the generated manifest.php.

This PR removes this restriction, making all icons defined in manifest.json available in the icon registry. However, icons that were previously public are now marked with "show_in_rest": true and are only available via the REST API. This ensures that only the restricted core set of icons remains available in the Icon block as before.

How?

• Replace "public": true with "showInRest": true in manifest.json.
• When generating manifest.php, always include the "show_in_rest": true or false field.
• This PR means that a stricter backward compatibility policy will be applied to a wider range of icons. In other words, once an icon is defined in manifest.json or manifest.php and shipped to the core, it can never be removed. See this document for more details. In the future, I might consider implementing a mechanism to deprecate icons in some way, for example, like this:

  [
  	{
  		"slug": "clock",
  		"label": "Clock",
  		"filePath": "library/align-right.svg"
  	},
  	{
  		"slug": "time",
  		"label": "Time",
  		"deprecated": true,
  		"alias": "clock"
  	}
  ]

Testing Instructions

Icon block

• Open the post editor and insert an Icon block.
• Open the Icon Library modal.
• Confirm that only icons defined as public will be displayed.

Confirm all registered icons

Check the registered icons using the following code.

add_action(
	'init',
	function () {
		$registry = WP_Icons_Registry::get_instance();

		// Output icons that are not exposed by the REST API.
		$icon_1 = $registry->get_registered_icon( 'core/accordion' );
		$icon_2 = $registry->get_registered_icon( 'core/background' );

		echo '<div style="display:flex;flex-wrap:wrap;gap:16px;">';
		echo '<div style="width:24px;">' . $icon_1['content'] . '</div>';
		echo '<div style="width:24px;">' . $icon_2['content'] . '</div>';
		echo '</div>';

		// Output all registered icons.
		$icons = $registry->get_registered_icons();
		echo '<div style="display:flex;flex-wrap:wrap;gap:16px;">';
		foreach ( $icons as $icon ) {
			echo '<div style="width:24px;">' . $icon['content'] . '</div>';
		}
		echo '</div>';
	},
	10
);

Use of AI Tools

Although most of the code was written by Claude, I reviewed all of it myself.

[github-actions]

Size Change: 0 B

Total Size: 7.51 MB

_{compressed-size-action}

[jasmussen]

Thanks for all the help with icons.

Just to be sure, does this PR make the icons public in the Icons block? I'd prefer if we still show only a limited subset there, because once they are available to that block, they are much harder to deprecate, which is something being discussed in context of the fresh energy there is in the icon space.

[t-hamano]

does this PR make the icons public in the Icons block?

No, if it hasn't been displayed in the icon block before, it won't be displayed as before.

However, icons that were previously public are now marked with "show_in_rest": true and are only available via the REST API. This ensures that only the restricted core set of icons remains available in the Icon block as before.

[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: tyxla <tyxla@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>

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

[jasmussen]

Thanks for the clarification, I missed the detail 🙏

[github-actions]

Flaky tests detected in 617f209.
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.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27330510023
📝 Reported issues:

• [Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

[mcsf]

Hey, @t-hamano!

I'm worried by this change. We introduced the public field precisely because we weren't confident about many of the icons in the core library. So we hid the non-public icons from any consumers interacting with the icons registry (whether directly or via the REST endpoint), but we kept them for our own uses within the client application. This distinction was easy to make because the latter was based on explicit JS imports and was "safeguarded" by the bundled nature of the Icons package.

But now I don't understand the reasoning behind hiding them in the controller while showing them in the registry. The registry is accessible by any third party. And so will wp_get_icon as proposed in #78332.

IMO, this change entails a change in "policy" around the core icon library, but as far as I can tell this fact isn't made explicit. If we're to proceed, shouldn't we audit the library to make sure we actually want to "promote" all the icons to registry-accessible?

[tyxla]

Noting that the icon manifest obviously grew a lot with this change. That's likely fine on its own, but I'm also considering the changes in #79100 where we're now essentially hydrating the content for every icon whose content is on the filesystem. That might mean hundreds of disk I/O operations; is it possible this will lead to a performance regression?

I'm not sure what the solution is, but maybe it makes sense to consider lazy hydrating the icon content, or maybe introducing some filtering so we don't call get_content() on icons that we won't really need yet.

[tyxla]

Should we add test for the show_in_rest REST API exclusion behavior?

[tyxla]

This also needs a test IMO.

[tyxla]

Test for this too?

[tyxla]

This seems to be fully reimplementing the parent class method. Should we try to reuse it as much as possible and just sprinkle the show_in_rest filter logic on top?

[tyxla]

Actually, what's the scenario to this path of the code? Won't parent::get_icon() already return a 404 for non-REST icons?

[tyxla]

When are we actually going to surface the translations for icons that we don't show in the REST API? It seems a bit wasteful to localize all those strings and add hundreds of new non-translated strings to core if we're never going to surface them to end users.

[tyxla]

Note that spacing will need to be aligned here.

[t-hamano]

Thanks for the review! Let me explain the intention behind this PR in a bit more detail.

But now I don't understand the reasoning behind hiding them in the controller while showing them in the registry. The registry is accessible by any third party. And so will wp_get_icon as proposed in #78332.

The @wordpress/icons package is not intended for frontend use. Therefore, we have limited the icons available to consumers via #75526. However, the SVG Icons API may be used throughout WordPress, not just the frontend, in the future. Please refer to https://core.trac.wordpress.org/ticket/65089 as an example. To comprehensively manage all WordPress icons through the SVG Icons API, I believe it is necessary to register all icons from the @wordpress/icons package in the icon registry.

Furthermore, the reason I changed public to show_in_rest is that I considered it to be similar to the existing approach in the core. For example, with register_meta and register_setting, whether the data is public is determined solely by show_in_rest. Data where show_in_rest is empty is excluded from the REST controller.

IMO, this change entails a change in "policy" around the core icon library, but as far as I can tell this fact isn't made explicit. If we're to proceed, shouldn't we audit the library to make sure we actually want to "promote" all the icons to registry-accessible?

I agree. I think we really need to scrutinize and remove icons that are not worth releasing to developers.

[mcsf]

Furthermore, the reason I changed public to show_in_rest is that I considered it to be similar to the existing approach in the core. For example, with register_meta and register_setting, whether the data is public is determined solely by show_in_rest. Data where show_in_rest is empty is excluded from the REST controller.

Right, I see the desire for symmetry, though it's apples and oranges:

While a registered meta key hidden from REST is indeed "visible" to third parties via PHP, the semantics of meta mean that any third-party access will be guarded (is the key registered? are there meta values for this key and this object ID?). Furthermore, Core itself rarely registers meta/settings of its own, and when it does it's usually understood to be an internal matter. All things combined, we can reasonably expect third parties to either not interact with meta that they haven't registered themselves, or be exceedingly defensive when doing so.

In contrast, icons are a resource/asset meant to be found and used. If any third party can enjoy icons by simply calling wp_get_icon( 'some-private-icon' ), it will be much harder to argue that those icons are sufficiently private, and we will end up responsible for preserving backwards compatibility.

---

I agree. I think we really need to scrutinize and remove icons that are not worth releasing to developers.

Pinging @jasmussen and @tyxla too:

With our original introduction of the public flag, we sought to reduce how many icons we were committing to supporting, but we subsequently tightened our list of public icons even more because there were several icons that we didn't want to be a part of the Icon block's gallery. Today, considering that the roadmap for the Icons registry includes support for categories, it seems like we could:

• Define a category of icons that are appropriate for the Icon block (most restrictive set)
• Determine which icons beyond that category we'd like to effectively make public
• Eliminate the show_rest distinction and reinstate public — unless there remains a compelling reason for show_rest that I've missed

Since the motivation for this PR and wp_get_icon is to allow efforts to modernise WP-Admin to take advantage of modern icons, why not make icons public on a case-by-case basis whenever those modernisation efforts are mature enough to dictate which icons they need?

[jasmussen]

Thanks for the ping, thansk for the review Miguel and thanks for the code Aki.

For me, what is important is that we can energise and use WordPress icons. It's a good set, we might soon add stroke-based scaling effects, and following up on that, a consistency pass, deprecate some icons. In fact I expect to redraw a fair bit of icons too. Aside enabling their usage to support an admin refresh, I would like to help make this set beautiful, and both easy and compelling to use. I'm quite excited for all of that, and feel like we are only a couple of decisions away from unblocking good energy here.

In saying that, I'm also clearly delineating what's my area of expertise, the design and the systematic approach for engaging with it. Which is to say, inline SVGs appears to be the most solid approach adopted broadly by the industry (with GitHub Octicons being a prime example of a great set that moved away from use). If that's not a PHP method for outputting inline SVGs, I'm truly happy to defer to you all on deciding.

And I can say with some confidence that I'd like to deprecate additional icons (such as some of the filled versions), and update others (such as insertBefore). For example if we deprecate plusCircleFilled, we can provide some form of deprecation by pointing to plusCircle instead, whether through a permanent or temporary additional export under the same name, and mark it as a breaking change in the README. But I can't say whether that same method for deprecating icons can work the same for a PHP API as it currently does for the React API.

And in both cases, I can't say for either, whether making all these icons "public" or not, is a good idea, like how we did in #75526. But I will say that the primary motivation with that reduction in the set was that, both then and as now, we knew we were going to clean things up further, and we didn't want to expand the API surface to the Icons block—public content on webpages. In that sense, I've always appreciated at least limiting icons in that block, which I understand remains in place regardless of the registry.

So I'll keep investing energy in icons, their design, updates, a few deprecations. And I've put on my todo list to create a list, like I did in #75526, of which icons I would denote as "at risk" at least as far as needing visual updates or possibly coming on the chopping block: I can have one ready tomorrow. What we do with such a list, I will trust into your capable hands.

[jasmussen]

Following up, and let me know if there's a better place to post these. Here's a list of icons, and their status, rather emotionally felt and extremely subjectively assessed with all the shortcomings that entails:

I want to emphasise the human fault possible in all this. These are my instinct. I'll elaborate, but I share them mainly to help any technical decisions happen, as far as how we might handle deprecations or updates in the future, as the API surface increases.

• Mostly stable: these are icons I think are in a pretty good place. They will most certainly receive small visual updates as we go forward, e.g. convert them to be stroke-based. There's a larger philosophical question of whether the entire set should move to a strict strokes-only based set, but I don't think that's fully feasible while maintaining that language. It could possibly become a prop of ancestor componentry, to not display fills for a cleaner look, and if we did that it would affect mostly things like "sidebar", or "star-half", "styles", and "symbolFilled" as far as needing a little conceptual rethinking if that were to happen. But best I can predict, these are likely to visually stay mostly intact.
• Could be improved are the icons I'd love to reinvent. A lot of the icons here come from the notion that "every bespoke block needs a bespoke icon", which is something I think needs a smarter system at least for core blocks. The idea itself is reasonable enough: the block in the list view needs to distinguish itself from its neighbours. But especially for template icons, like "post content", "term-name" and other exotic blocks, I feel like there's a visual language waiting for us to find it, which drastically simplifies this vocabulary. Some of the other icons are just icons that are pretty nice but could be visually tweaked a little, to be nicer. E.g. "caption" is a nice icon, but it doesn't really read as much like captions as a [CC] icon might. Other icons such as media & text, or receipt, simpy have their text-lines too close to each other compared to the others.
• Needs improvement are icons that can benefit from substantial visual updates, and not because they are necessarily poor. E.g. the sub/supertext icons simply need some font-weight clarity that's lacking, some of the design concepts are not clear enough, the pin and cloud icons are fuzzy, the keyboard icon is a dashicon and possibly unused. The send icon is nice, but has some corner-radii that are off, and it might benefit from becoming stroke-based. The RTL icons are very close to indent/outdent, and not clearly different enough.
• Needs thought/stroke-based is a category of icons that will need some careful rethinking as to their utility. We clearly need icons for bold and italic, but it would likely be nice to redraw them so their font-weight changed along with a stroke-weight, based on incoming tech. Definitely possible, but something to carefully mull over, and it could change the appearance slightly, certainly the optical footprint across could be improved. And then there are icons like the stroke-type—dashed, dotted, solid line, as well as the padding-directions. These are very much functional SVGs built for particular block-tool contexts, and it's an open question whether they should be published along with the library at all; consider "reset" (just a minus) is virtually identical to "line-solid". The unlocked icon exists in that bucket because in context of stroke-based conversations we should consider whether it makes sense to have both a solid and an outline version of the lock icons. Right now we have "lock", "lockOutline", and "unlock", which seems one too many.
• Deprecation candidates are the icons that could be deprecated in the future, again not necessarily as an expression of their quality, but for other reasons. The help, close, and notice and plusCircleFilled icons are filled versions of outline versions that we might not need. The "copy-small" seems like it should either replace the default "copy" icon, or just go away, not an icon we need two of. The "home" icon was added for an older experiment that I don't think moved forward. The Wifi icon was added for the mobile React scaffolding which is now gone. The "classic" icon is for the classic block, but it's very close to the keyboard and it's unclear we need both. The insertbefore/after were very old dashicons that were ported over then never used. The small pin icon could need some thought too, I think it was created to indicate "pinned", but it doesn't read well or serve a strong purpose in this iteration.

Let me know if this tells us anything about next steps, or is useful otherwise. I don't necessarily attach a timeline to any of this: my first order of business is to enable us to use at least some of our WordPress icons in places we currently use Dashicons, second order of business is to convert the whole set to be stroke-based.

Edit: see this comment about pullquote.

[mcsf]

Thanks for the detailed answer, Joen! It all sounds reasonable, though I should be clear that I'm no position to consider the fate of the icons themselves. :)

I would ask one thing, which is to attach your categorisation to this thread as text (i.e. as lists of slugs), so that we can easily apply/repro the classification in development.

my first order of business is to enable us to use at least some of our WordPress icons in places we currently use Dashicons

Sounds good. In this set contained within the Mostly Stable set?

[jasmussen]

In this set contained within the Mostly Stable set?

Should be, yes. Perhaps lock, unlock, and cog, are ones that have broad utility as well, but we can negotiate details if it comes to that.

Here are the same icons, in text. Note, these are based on the SVG filenames, which in order to be jsx names I think you need to convert them to camelcase. I.e. add-card → addCard.

Mostly stable

• add-card
• add-template
• align-center
• align-justify
• align-left
• align-none
• align-right
• arrow-down
• arrow-down-left
• arrow-down-right
• arrow-left
• arrow-right
• arrow-up
• arrow-up-left
• arrow-up-right
• aspect-ratio
• at-symbol
• audio
• background
• backup
• bell
• block-default
• block-meta
• block-table
• border
• box
• button
• buttons
• calendar
• capture-photo
• capture-video
• cart
• category
• caution
• chart-bar
• check
• chevron-down
• chevron-down-small
• chevron-left
• chevron-left-small
• chevron-right
• chevron-right-small
• chevron-up
• chevron-up-down
• chevron-up-small
• close
• close-small
• cloud
• code
• column
• columns
• comment
• copy
• corner-all
• corner-bottom-left
• corner-bottom-right
• corner-top-left
• corner-top-right
• cover
• create
• crop
• currency-dollar
• currency-euro
• currency-pound
• dashboard
• desktop
• download
• drafts
• drag-handle
• drawer-left
• drawer-right
• envelope
• error
• external
• file
• filter
• flip-horizontal
• flip-vertical
• footer
• format-indent
• format-list-bullets
• format-list-bullets-rtl
• format-ltr
• format-outdent
• format-rtl
• fullscreen
• funnel
• gallery
• gift
• globe
• grid
• group
• handle
• header
• heading
• help
• home
• image
• inbox
• info
• institution
• justify-bottom
• justify-center
• justify-center-vertical
• justify-left
• justify-right
• justify-space-between
• justify-space-between-vertical
• justify-stretch
• justify-stretch-vertical
• justify-top
• key
• keyboard
• keyboard-return
• language
• layout
• level-up
• lifesaver
• link
• link-off
• list
• list-item
• list-view
• lock-outline
• lock-small
• login
• loop
• map-marker
• math
• megaphone
• menu
• mobile
• more-horizontal
• more-vertical
• navigation
• next
• not-allowed
• page
• page-break
• pages
• paragraph
• payment
• pencil
• pending
• people
• plus
• plus-circle
• position-center
• position-left
• position-right
• previous
• published
• pull-left
• pull-right
• quote
• redo
• reset
• resize-corner-n-e
• reusable-block
• rotate-left
• rotate-right
• row
• rss
• scheduled
• search
• seen
• separator
• settings
• shadow
• share
• shield
• shipping
• shortcode
• shuffle
• sidebar
• site-logo
• square
• stack
• star-empty
• star-filled
• star-half
• store
• stretch-full-width
• stretch-wide
• styles
• swatch
• symbol
• symbol-filled
• table
• table-column-after
• table-column-before
• table-column-delete
• table-of-contents
• table-row-after
• table-row-before
• table-row-delete
• tablet
• tag
• thumbs-down
• thumbs-up
• tip
• trash
• trending-down
• trending-up
• undo
• ungroup
• unseen
• update
• upload
• verse
• wordpress

Could be improved

• add-submenu
• archive
• brush
• bug
• caption
• cog
• color
• comment-author-avatar
• comment-author-name
• comment-content
• comment-edit-link
• comment-reply-link
• connection
• custom-link
• custom-post-type
• details
• media
• media-and-text
• more
• move-to
• overlay-text
• percent
• pin
• plugins
• post
• post-author
• post-categories
• post-comments
• post-comments-count
• post-comments-form
• post-content
• post-excerpt
• post-featured-image
• post-list
• post-terms
• preformatted
• query-pagination
• query-pagination-next
• query-pagination-numbers
• query-pagination-previous
• receipt
• remove-bug
• remove-submenu
• replace
• term-name
• title
• tool
• video
• widget

Needs improvement

• breadcrumbs
• cloud-download
• cloud-upload
• format-indent-rtl
• format-outdent-rtl
• keyboard-close
• send
• subscript
• superscript

Needs thought/stroke-based

• format-bold
• format-capitalize
• format-italic
• format-list-numbered
• format-list-numbered-rtl
• format-lowercase
• format-strikethrough
• format-underline
• format-uppercase
• heading-level-1
• heading-level-2
• heading-level-3
• heading-level-4
• heading-level-5
• heading-level-6
• html
• line-dashed
• line-dotted
• line-solid
• not-found
• post-date
• sides-all
• sides-axial
• sides-bottom
• sides-horizontal
• sides-left
• sides-right
• sides-top
• sides-vertical
• term-count
• term-description
• text-color
• text-horizontal
• text-vertical
• typography
• unlock
• word-count

Deprecation candidates

• bell-unread
• cancel-circle-filled
• caution-filled
• classic
• copy-small
• help-filled
• home-button
• insert-after
• insert-before
• lock
• offline
• pin-small
• plus-circle-filled
• time-to-read

Edit: see this comment about pullquote.

[tyxla]

With our original introduction of the public flag, we sought to reduce how many icons we were committing to supporting, but we subsequently tightened our list of public icons even more because there were several icons that we didn't want to be a part of the Icon block's gallery. Today, considering that the roadmap for the Icons registry includes support for categories, it seems like we could:

• Define a category of icons that are appropriate for the Icon block (most restrictive set)
• Determine which icons beyond that category we'd like to effectively make public
• Eliminate the show_rest distinction and reinstate public — unless there remains a compelling reason for show_rest that I've missed

Since the motivation for this PR and wp_get_icon is to allow efforts to modernise WP-Admin to take advantage of modern icons, why not make icons public on a case-by-case basis whenever those modernisation efforts are mature enough to dictate which icons they need?

I agree that we should seek simplicity here, and a show_in_rest flag may not be necessary if we utilize public.

[jasmussen]

An important correction to this list, the pullquote icon should not be a deprecation candidate. I had mistakenly thought the Pullquote block itself had been deprecated, it appears to be back, and so of course the Pullquote icon should remain.

[t-hamano]

Thank you all for your wonderful suggestions.

My final thought is to postpone this PR to 7.2. The icons still have room for improvement, and I think we should discuss more carefully which ones should be released. For now, it might be better to focus on improving the existing icon registry and shipping the custom icon registration API. The custom icon registration API is likely the most requested feature by consumers.

[jasmussen]

My final thought is to postpone this PR to 7.2. The icons still have room for improvement, and I think we should discuss more carefully which ones should be released.

Thanks for all the energy. Just to be sure I understand correctly: does #78332 depend on this PR in order to land in 7.1, or do you propose both are postponed to 7.2? I don't know that I have strong opinions either way, just making sure I understand.

[t-hamano]

does #78332 depend on this PR in order to land in 7.1, or do you propose both are postponed to 7.2?

No, this PR and 78332 are not dependent on each other. I believe that #78332, at least, can be shipped for 7.1.

[t-hamano]

Let me explain my intentions regarding this PR a bit further.

If the API for custom icon registration becomes available in #77260, consumers will be able to register icons with code like the following:

add_action( 'init', function () {
	wp_register_icon_collection( 'my-icons', array(
		'label'       => 'My Icons',
	) );
	wp_register_icon( 'my-icons/star', array(
		'label'   => 'Star',
		'content' => '<svg></svg>',
	) );
}, 20 );

What if consumers want to control whether their blocks should be displayed in the Icon block?

add_action( 'init', function () {
	wp_register_icon_collection( 'my-icons', array(
		'label'       => 'My Icons',
	) );
	// Since this icon is intended to be used within the content,
	// make it available in the Icon block.
	wp_register_icon( 'my-icons/star', array(
		'label'        => 'Star',
		'content'      => '<svg></svg>',
		'show_in_rest' => true,
	) );
	// This icon is used on the server-side or for the dashboard.
	wp_register_icon( 'my-icons/star', array(
		'label'   => 'Gear',
		'content' => '<svg></svg>',
	) );
}, 20 );

I feels like we need some option to control whether an icon should be used in post content, perhaps via a key like "public", "show_in_rest", or something similar.

[tyxla]

@t-hamano my understanding was that we're good with a public flag, but there's no need for 2 different flags (show_in_rest AND public). @mcsf please correct me if I'm wrong. If that's the case, what else are we missing here?

[mcsf]

please correct me if I'm wrong. If that's the case, what else are we missing here?

Sounds right. And, for future readers, we seem to agree on a "ternary" public flag as described here: #79451 (comment)

[t-hamano]

Thank you, everyone. For now, it seems best to decide on the icons to be published with only the public fields mentioned in #79451 (comment). Let's close this PR for now.