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

[fushar]

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

Warning

This PR needs this Gutenberg PR to work: WordPress/gutenberg#79451 (and later backported).

Until then, you can test it via this Playground link: https://playground.wordpress.net/?core-pr=12270&gutenberg-pr=79451

TODO: revert the "TEMPORARILY add non-public icons" commit after the backport lands.

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/sites
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/pin	❌
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. Updated to core/sites from Icons: Add "sites" icon. gutenberg#80094.
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.

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

Props fushar, jeffpaul, tyxla, fcoveram, mcsf, wildworks, keoshi, joen, afercia, ugyensupport, mrwweb.

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: ship required icons for admin bar and menu with public: false 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 🤔

[jasmussen]

Noting that I'm responding here to some feedback on the core post, just to consolidate it all in one place. I will follow up and link to this comment from the comments.

The feedback fell in two categories:

1. which icon to best use for their dashicon counterparts
2. optical balance: some being bigger, some being smaller.

For this PR I think we should update the icons to what agreement is found as far as which icons to use, pin vs. verse, etc. As for the actual optical balance changes, upon agreement I will make a PR to the componentry source and we can then follow up shortly after with a new PR here. It's important to know the context and the followup, even if we do it in two phases.

I tried to address as much as possible in the mockup below:

Set	Mockup

• Testing a new larger "brush" icon, closer to its original sibling counterpart.
• Gallery icon instead of "image" for Media.
• New optically balanced Pin icon for Posts
• New optically balanced comment icon for comments.
• Visually updated Tools icon, stroke based
• Updated Settings icon

I personally think this one gets us closer as far as balance, though @mrwweb makes a good point that is notably visible in the bottom group of icons:

The icons themselves feel like what they are—an assemblage of icons designed for different purposes through the WP UI

There's an aspect of the icons having organically built up separately, as also tracked here. As part of the effort to convert to stroke-based, however, small improvements have been made to a number of icons specifically to address the points raised there, and extending that set for this collection of main admin icons feels valid. For me what stands out is that there are many diagonal icons in the utility section that causes a bit of a mix. Here's an attempt at addressing this head on:

Set	Mockup

• The Plugins icon is now adjusted, polished, and tipped 45 degrees.
• There's a new "Media" icon, that's closer to the source material.

The rework of the plugins icon makes it immediately feel like it belongs next to tools and appearance.

I'm not too sure about the new Media icon: I honestly prefer using something simpler like just a single "image" icon. But there is some value in recognition that's worth acknowledging.

---

In defence of the "Verse": the following I want to acknowledge as good feedback:

re: the posts icon – I think the iconography is too similar to the updated appearance icon. And while the Verse block certainly isn’t an everyday block for most sites, it feels odd to reuse it for the original post type. I didn’t do a full audit, but I wonder about other icon purposes overlapping that might create confusion, even if infrequently.

Perhaps with a larger brush, the Verse icon can be reintroduced as it no longer looks similar. Nevertheless, the post type point is worth noting. I think of this as the quill pen icon, that happens to be used for the Verse block, and thus the connection between block and type didn't occur to me.

WordPress may be the last bastion of the open web. Its users write, without arbitrary limitation from closed platforms, never locked in. There's some beauty to that which feels like poetry. So for me using the quill pen icon is more a matter of bringing that character into WordPress—code is poetry, after all.

In the process of redrawing icons to be stroke-based, I also tried some stress tests to validate the point of stroke-based, namely that you can contextually set the weight:

It's likely not a UI we'll use anywhere—or could it become part of a mobile effort? In any case, next to "Page", the quill pen just looks beautiful to me.

In any case, I'll be delighted for WordPress to get fresh energy on the icon side. For now, the main action item on these mockups is to agree on: which icons should we use? If we find agreement on those, I will follow up on the icon design changes based on that agreement and we can make a new PR. Is that fair?

---

To note, a suggestion was to use the "styles" icon for the Apperance section. I tried that below, and I think it could work if also replacing some of the other utility icons.

View

[mrwweb]

@jasmussen These changes all feel both very responsive to the overall feedback and like really meaningful improvements!

The plugins icon feels especially better cleaned up and tilted 45 degrees! I like the direction of the new Media Library icon, though there's something about the music notes that is maybe slightly too heavy. (That's a super nit pick, and it feels much more cohesive than the old one). I also like the settings icon change that was suggested. Really nice work!

I like your points in defense of the quill icon, writing, and the open web. I think there's something there. The new distinctive paintbrush icon solves what felt like the bigger of the two issues with the quill not being distinctive enough. Personally, I've never loved the pin icon either, so I like your idea of a change for Posts.

I haven't thought about this deeply, but I wonder if a fountain pen icon could potentially have the same meaning without any risk of ambiguity? (Pencil is presumably still reserved for editing.) Here's a noun project icon purely as a directional composition idea that could use a 45 degree angle.

[jeffpaul]

In any case, next to "Page", the quill pen just looks beautiful to me.

In any case, I'll be delighted for WordPress to get fresh energy on the icon side.

Totally agree, beautiful!

@fushar How does the before/after look for an RTL site?

[jasmussen]

Thank you all for the feedback. Noting that for now I've updated the "after" image (including a tiny slipstreamed tweak to make the musical note in "media" ever so slightly smaller) on the general make/core post.

In general I pledge to follow up on any details that emerge from conversation in followups—the fountain pen idea is a good one—though perhaps before I go much deeper it's better to give additional feedback a chance to land, and for Ashar to update this PR with the latest choices. I will then separately start to prep the new icons for inclusion in the library. Sound good?

[fushar]

@fushar How does the before/after look for an RTL site?

@jeffpaul It looks like this 🙂

Before	After

[fushar]

and for Ashar to update this PR with the latest choices.

@jasmussen I updated this PR (and the screenshots) with core/pin for Posts, and core/settings for Settings!

I'll try to revive the Gutenberg PRs which are necessary to get the non-public icons in for this PR.

[jasmussen]

Thanks. I will also follow up ASAP on the new and adjusted icons shown in this thread.

[fushar]

For anyone following along, the latest state of the PR can be tested using this special Playground link: https://playground.wordpress.net/?core-pr=12270&gutenberg-pr=79451 🙂

[dugyen]

Re-tested this via the Playground link in the description (core PR + Gutenberg PR 79451), since core alone can't render this without the icon backport.

Verified working:

• Sidebar icons (Dashboard, Posts, Media, Pages, Comments, Appearance, Plugins, Users, Tools, Settings, Collapse) render as real inline <svg>, not broken/missing glyphs — confirmed via DOM inspection, not just visually.
• Admin bar icons (WP logo, Site Name/home, Menu toggle, Search, +New, Comments) render with the correct icon per item.
• Hover/current-item highlighting still recolors the SVG (fill: currentColor + hover rules).
• Folded/collapsed sidebar mode renders correctly, icon-only.
• No console errors or 404s tied to icons; dashicons.css still loads fine as a residual dependency for the parts not yet converted.

One thing I suspected from reading the diff but disproved by testing: the CSS deletes several #wpadminbar #wp-admin-bar-<item> > .ab-item::before { width: 52px; height: 46px; ... } mobile (≤782px) rules with no obvious SVG replacement, which looked like a mobile-icon-sizing regression on first read. Checking computed styles at a 375px viewport showed it's fine — a pre-existing generic rule (#wpadminbar .ab-icon, #wpadminbar .ab-icon.svg-icon { width: 52px; height: 46px; ... }) already covers the new .ab-icon elements, so the deleted per-ID rules were dead code once the icon moved from ::before onto a real element. No action needed.

Suggestions (non-blocking):

1. Dead CSS in the mobile media query: admin-bar.css still applies font: 40px/1 dashicons !important; to the new .ab-icon.svg-icon selector even though SVG sizing is fully controlled by the separate svg { width/height } rule added right after it. Harmless, but worth trimming for clarity.
2. Redundant aria-hidden: _wp_admin_bar_icon(), the collapse-button span, and the .wp-menu-image wrapper in menu-header.php all set aria-hidden="true" on the wrapper and wp_get_icon() already sets it on the inner <svg> by default. Not wrong, just duplicate.
3. Not exercised in this pass: RTL layout, multisite/network-admin sidebar, and the "has site icon" branch of the admin bar (my test site had no site icon and wasn't multisite). Worth a manual pass on those before merge.

Traced the icon-selection logic (menu.php's $builtin/WP_Icons_Registry::is_registered() branch, wp_admin_bar_site_menu()'s home-vs-dashboard choice, the dashicons-/data:image/svg+xml/registered-icon fallback chain in _wp_menu_output()) against the PR's before/after table and it's consistent — no logic bugs found. PHPUnit/QUnit fixture updates correctly match the new icon slugs.

Nice work overall — only minor cleanup opportunities, nothing blocking.

[fushar]

Something is not right, it seems the above Playground link is not serving the latest state of this PR (the Posts sidebar is showing blank instead of pin). Let me think...