Admin: replace dashicons in admin bar and sidebar with @wordpress/icons

[fushar]

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

Warning

This PR is stacked on top of #12010. Please only review my commit: 3fc4ca4

Also, some icons were not already public, so they need to be made public, maybe as separate Gutenberg PR. See related: WordPress/gutenberg#79102.

This PR replaces the dashicons usage in admin bar and menu (sidebar) with @wordpress/icons, via the newly-introduced wp_get_icon() function, which outputs an inline SVG to be rendered.

New icon mapping

Admin bar

Item	Old dashicon	New wp/icons	Public?
WordPress logo	dashicons-wordpress	core/wordpress	❌
Sidebar menu toggle (mobile)	dashicons-menu-alt	core/menu
My Sites	dashicons-admin-multisite	core/block-meta
Site Name — frontend	dashicons-dashboard	core/dashboard	❌
Site Name — wp-admin	dashicons-admin-home	core/home
Edit Site Customize	dashicons-admin-appearance dashicons-admin-customizer	core/brush	❌
Edit (post/page/etc.)	dashicons-edit	core/pencil
+ New	dashicons-plus	core/plus
Comments	dashicons-admin-comments	core/comment
Updates	dashicons-update	core/update	❌
Search Command Palette	dashicons-search	core/search
My Account (no-avatar fallback)	dashicons-admin-users	core/people

Admin menu (left sidebar)

For simplicity, only showing new items not present in the admin bar above.

Menu item	Old dashicon	New wp/icons	Public?
Posts	dashicons-admin-post	core/post	❌
Media	dashicons-admin-media	core/media	❌
Links	dashicons-admin-links	core/link	❌
Pages	dashicons-admin-page	core/page	❌
Plugins	dashicons-admin-plugins	core/plugins	❌
Tools	dashicons-admin-tools	core/tool	❌
Settings	dashicons-admin-settings	core/settings
Collapse menu button	dashicons-admin-collapse	core/chevron-left

Open questions

1. I'm not sure about My Sites icon. The closest thing that I think fits is the core/grid icon (see screenshot below). Open to alternatives. Updated to core/block-meta for the time being, still open to alternatives.
2. The search/magnifier icon is facing the opposite direction from the old dashicon. Should we do something about it? My vote is to do nothing; if we want to reverse the direction, we should update the icon instead.

Screenshots

WP Admin

Before	After

WP Admin - Multisite

Before	After

Frontend

Before

After

Mobile

Before

After

Use of AI Tools

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

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

Hi there! 👋

Thank you for your contribution to WordPress! 💖

It looks like this is your first pull request to wordpress-develop. Here are a few things to be aware of that may help you out!

No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description.

Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making.

More information about how GitHub pull requests can be used to contribute to WordPress can be found in the Core Handbook.

Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook.

If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook.

The Developer Hub also documents the various coding standards that are followed:

• PHP Coding Standards
• CSS Coding Standards
• HTML Coding Standards
• JavaScript Coding Standards
• Accessibility Coding Standards
• Inline Documentation Standards

Thank you,
The WordPress Project

[github-actions]

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.

[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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @1178653+wordpress-develop-pr-bot[bot]@users.noreply.github.com.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Props wildworks, fushar, jeffpaul, tyxla, fcoveram, mcsf, keoshi.

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

[fushar]

cc-ing (maybe) interested parties :) @t-hamano @jasmussen @tyxla @scruffian @lucasmendes-design

[jeffpaul]

These all appear to be solid like-for-like replacements, though I feel least supportive of the Sites icon replacement on multisite. Perhaps a new icon could/should be generated there or review other icons for something besides a 2x2 table sort of icon? Of the existing icons, the one that feels like what I'd recommend otherwise is one that looks like a "two child node branched to the right" (sorry GitHub is giving me problems trying to upload a screenshot from my cell connection).

[fushar]

@jeffpaul Thanks for checking!

I feel least supportive of the Sites icon replacement on multisite.

Yep, as noted in the PR description, I'm not sure about this as well.

Of the existing icons, the one that feels like what I'd recommend otherwise is one that looks like a "two child node branched to the right"

You mean core/blockMeta? Indeed this looks more fitting. 😄

But my worry is that the icon slug is not related to "site" at all. I would expect there is something like core/sites icon. Perhaps it's better if we create a new such icon. cc: @jasmussen, @lucasmendes-design (I know you're all on vacation, feel free to respond when you're back.) @fcoveram

Another idea is to use this icon, to represent a "site switcher":

[tyxla]

A few things from my end as I'm looking at this work:

• This is exciting and a much-awaited overhaul of icons, love it!
• It has the potential to have an impact on many plugins, plugin infrastructures and products that rely on the current icon set - something to be mindful about
• I don't see enough feedback from @WordPress/gutenberg-design on this, and I believe this is a hard requirement
• I believe it's a bit late in the 7.1 cycle for this to move forward, but it makes sense to get it to the finish line on time for landing early in the 7.2 cycle. It's paramount to give plugins and extenders enough time for testing and adopting the necessary changes.
• An angle that doesn't seem explored is trying this out as a Gutenberg experiment - not only to allow for safe iteration, but also as yet another way to get useful feedback.

[jeffpaul]

@fushar yes the blockMeta was the icon I was trying to reference, though I'm not quite as concerned with the slug for it (not certain that the slug is referenced or rendered anywhere in the UI and if not then there's no end user confusion that could happen). I'm not much in favor of the chevronUpDown option for Sites, in that case would just stick with the 2x2 table-looking icon I suppose but in any case would like a better one for that icon if possible (and if as @tyxla notes this is too late for 7.1 then we've got some time to iterate on the Sites icon).

[fushar]

An angle that doesn't seem explored is trying this out as a Gutenberg experiment

Thanks for the suggestion. I spent a good chunk of my day today trying to make this as a Gutenberg experiment.

With the help of Claude, I (we) came up with this PR: WordPress/gutenberg#79588. Now, I understand that the changes are complicated, but I can't simplify it any further. Reasons:

• I need to render the icons that are not yet public. wp_get_icon() won't allow me to render such icons, so I need to replicate the implementation for now.
• There's no way to hook into admin menu icon. Basically I really need this new logic in Core, which can't be extended via hooks. Hence the experiment needs to hijack the output of the admin menu HTML and replace dashicons with SVG before it gets rendered.
• The CSS needs to duplicate the admin color scheme to achieve hover effect in the admin bar. In this Core change, I can just update the _admin.scss directly, which can't be replicated in experiments.

Am I approaching this correctly? Or do you have better idea for a cleaner approach? Thanks!

cc: @mcsf

[fcoveram]

It looks great ✨ I noticed a few things that I'm not fully sure belong to the PR scope.

Icon size

In most cases, the icon size is 22px, but the W symbol is 24px.

22px	24px

Not sure if this is intentional or not.

Color on the frontend

On the frontend, the color at 0.6 looks slightly lighter. I know it is consistent, but at 0.85 looks visually more similar to the current. This is not a blocker but sharing it for thoughts.

"Sites" icon

Regarding the icon for Sites, I agree that blockMeta works well until having a dedicated icon.

---

I've been testing it on Arc, Chrome, and Safari and on multiple viewports. And they all look good ⭐

[tyxla]

Am I approaching this correctly? Or do you have better idea for a cleaner approach?

Hmm, this seems correct to me. There are side ways for achieving some of the things you mentioned, but not for others, unless we want to be super hacky. A bummer that this part of the menu is not as extensible as usual. Thank you for trying, though.

Another way to get more attention on this would be to post a call for testing on the https://make.wordpress.org/core blog.

[mcsf]

Am I approaching this correctly? Or do you have better idea for a cleaner approach? Thanks!

I'd say so, at least for the purposes of a Gutenberg experiment. I left a comment or two in that PR.

[fushar]

yes the blockMeta was the icon I was trying to reference

@jeffpaul: I agree that it looks better than a 2x2 grid. For the purpose of demonstration, I updated this PR to use that for the time being:

[fushar]

@fcoveram: Thanks for the thorough testing!

In most cases, the icon size is 22px, but the W symbol is 24px.
Not sure if this is intentional or not.

Yeah, it is intentional. I'm not sure if it's the best way though. It's to achieve the same look and feel with the existing W dashicon. See the above image comparison, pasted here again:

Right now, if we use 22px, then the W logo is too small, because there's outer gap in the SVG. Maybe we need to fill the entire SVG box without any outer gap.

On the frontend, the color at 0.6 looks slightly lighter. I know it is consistent, but at 0.85 looks visually more similar to the current.

Yeah agree that 0.85 looks better. But I'm not sure if we can just update it only for the SVG icon. It's part of the Fresh color scheme; maybe we should do a separate PR to update the scheme 😄

[fushar]

All right everyone, thanks for taking a look. I want to summarize where we're at with this PR:

• To use currently non-public icons, we need the public: false flag as discussed in Icons: publicize required icons for admin bar and menu gutenberg#79451 (comment).
  • @t-hamano, is this something that you're currently pursuing? How confident are we with the solution?
• This PR adds support to use registered icons in left sidebar menu items. See this diff. To move forward, I need a review on this as it's modifying a public hook (admin_menu).
  
  • Also, maybe we should at least ship this part first in 7.1 so that plugins can start using it?
  • If we do that, it will be beneficial to ship the CSS changes for rendering SVG icons in admin bar / menu.
• We need to iterate on My Sites icon. I can ask for help for this. @jasmussen / @lucasmendes-design should be interested.
• As suggested, we should publish a public Make post as a heads-up to the community and plugin developers. In the post, we should suggest the default (core) icon set for the admin, and how plugins can use SVG icons in the admin menu (the public API change I mentioned above).

It feels like there's interest to push at least some parts of it in 7.1, and we're not that sure if we can achieve everything by 7.1. @t-hamano, what's your opinion on this? It seems you have the most context for all this icon API discussion 😄

cc: @tyxla, @mcsf, @scruffian.

[t-hamano]

It feels like there's interest to push at least some parts of it in 7.1, and we're not that sure if we can achieve everything by 7.1. @t-hamano, what's your opinion on this? It seems you have the most context for all this icon API discussion 😄

Leveraging the icon API for the dashboard icons is a great idea, and introducing a public:false flag shouldn't be difficult. However, I noticed that core icons might be unregistered by consumers.

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

add_action( 'init', function () {
    wp_unregister_icon( 'core/info' );
}, 20 );

In this case, what happens to the core menu icons registered by the icon API? This is my biggest concern. Here are the ideas I can come up with at the moment:

• Allow file paths for menu_icon. This ensures that icons are rendered even if they are unregistered from the icon registry, as the file itself will still exist within the core.
• Allow SVG strings for menu_icon. This might be a larger undertaking, requiring a proper SVG processing pipeline.
• Introduce a "built-in" collection to house icons used in dashboards and protect the unregisteredion of this collection or its icons would enhance robustness.

Do you have any other ideas?

[fushar]

Thanks for taking a look.

I noticed that core icons might be unregistered by consumers.

Hmm interesting question. I would say, the last option (consider core/* as built-in icon set which can't be unregistered) looks the most sensible to me. It's like having a fixed set of dashicons-* slugs that consumers can always use currently.

Otherwise, we will also need another way to get the SVG string for the admin bar icons as well, because in this PR I also use wp_get_icon() to prepend the icon to the title 🤔

[mcsf]

However, I noticed that core icons might be unregistered by consumers.

This is a good point.

• Allow file paths for menu_icon. This ensures that icons are rendered even if they are unregistered from the icon registry, as the file itself will still exist within the core.

One of the problems here is that it makes it more difficult to iterate on icon designs in Gutenberg, since those icons will no longer override those in wp-includes.

It also may or may not add some work for certain WP installations that rely on CDNs for core assets...? This is unfamiliar territory for me.

• Allow SVG strings for menu_icon. This might be a larger undertaking, requiring a proper SVG processing pipeline.

Sounds risky and heavy-handed, as you point out yourself.

• Introduce a "built-in" collection to house icons used in dashboards and protect the unregisteredion of this collection or its icons would enhance robustness.

Maybe, but it could make things frustrating for certain admins. For example, if — say, for editorial purposes — they'd like to keep a very narrow set of available icons for the Icon block. I don't think it's unheard of to prevent deregistering a core provision, but we almost always allow it (e.g. wp_deregister_script, unregister_block_type...). (Side note: we can always explore a separate mechanism for the Icon block so that third parties can filter its list of available icons.)

There's a fourth option, loosely in response to the one above:

Allowing core icons (and core collection) to be deregistered, so that they will not show up in listings, but embedding a fallback somewhere (WP_Icons_Registry::get_registered_icon? wp_get_icon?) so that certain core icons will still render.
^ I don't exactly like the idea, but I thought I'd share it anyway.

Another option is to honour admins' decision to deregister things, and have a fallback "no-icon" icon. In other words, make admins and extenders responsible for the questionable decision to deregister core icons: they can do it, but the admin will look weird with placeholder icons.

[t-hamano]

Another option is to honour admins' decision to deregister things, and have a fallback "no-icon" icon. In other words, make admins and extenders responsible for the questionable decision to deregister core icons: they can do it, but the admin will look weird with placeholder icons.

Is it possible to extend this idea further and display the relevant dashicon as a fallback if the SVG icon is not registered?

[keoshi]

One point to add to @fcoveram comment here:

In most cases, the icon size is 22px, but the W symbol is 24px.

All @wordpress/icons icons were designed with a 24×24px area in mind and all/most are optimized to be visualized at that size. Certainly in non-retina displays. Not sure if a deal breaker or not, so pinging @jasmussen to get your thoughts.

[tyxla]

Hmm interesting question. I would say, the last option (consider core/* as built-in icon set which can't be unregistered) looks the most sensible to me. It's like having a fixed set of dashicons-* slugs that consumers can always use currently.

This might make sense since this is how post types work - you can't unregister_post_type() a built-in post type. But for that to work, post types also maintain a _builtin flag. Seems like this is yet another "flag" to consider for icons.

[tyxla]

A high-level flag from me: the fact that we are still asking and answering fundamental API/design questions (registration/unregistration/compatibility) less than a couple of weeks before beta is a clear sign that a feature might need more time to get feature-complete, thoroughly thought out, and polished enough for a WordPress release. For some of that work, we might want to get broader feedback through a Make post, too, and that, on its own, will require some time to get meaningful feedback.