Make WordPress Core

Opened 7 months ago

Closed 3 weeks ago

Last modified 2 days ago

#65089 closed enhancement (fixed)

Administration: Replace Dashicons icon font with @wordpress/icons SVG components in wp-admin

Reported by: lucasmdo Owned by: mcsf
Priority: normal Milestone: 7.2
Component: Administration Version:
Severity: normal Keywords: needs-design needs-design-feedback has-patch has-unit-tests needs-docs needs-user-docs add-to-field-guide commit has-dev-note
Cc: Focuses: ui, accessibility, javascript, css, administration, performance

Description

Problem / Current Behavior

The WordPress admin area (wp-admin) still relies on Dashicons, an icon font introduced in WordPress 3.8 (released December 12, 2013 — over 12 years ago). While Dashicons served WordPress well, the icon font approach has significant limitations:

  • Inconsistency: The block editor and Site Editor already use @wordpress/icons (SVG-based React components), while the rest of wp-admin uses the legacy Dashicons font. This creates a visual and technical split within the same application.
  • Performance: The entire icon font (~300+ glyphs) is loaded, regardless of how many icons a page actually uses. This adds unnecessary weight to every admin page load.
  • Accessibility:
    • Screen readers: Icons may be read as nonsense or ignored entirely, confusing users who rely on assistive technology.
    • Font overrides: Users who change fonts for readability can break all icons, turning them into empty squares.
    • Copy-paste: Copying text that includes icons produces random, meaningless characters.
    • High-contrast mode: Icons can vanish when users enable high-contrast or forced-colors settings in their OS.
    • No built-in meaning: Icon fonts are just styled characters with no inherent description — accessibility has to be added manually.5.5. No new icons can be added.

Proposed Enhancement

Replace Dashicons icon font usage in wp-admin with @wordpress/icons SVG components (or inline SVGs derived from the same library). This would:

  1. Unify the icon system across all of WordPress, block editor, Site Editor, and classic admin screens would all use the same modern icon library.
  2. Enable tree-shaking so that only the icons actually used on a given page are loaded.
  3. Improve accessibility: inline SVGs support aria-label for example.
  4. Allow new icons to be added as needed without growing a monolithic font file.

Rationale

This is not a new idea, it has been the stated direction of the WordPress project since 2020:

  • The ​Make/Design blog post (April 2020) confirmed Dashicons was closed to new requests and that future efforts would focus on the new Icon component.
  • 49913 explicitly states: "This update is the final planned update of the Dashicons font. Moving forward, the more modern approach of using SVG icons directly (as the block editor currently does) will be explored."
  • 47498 comments reference "a long standing plan to remove all font icons from core in favor of SVGs."

Six years have passed since this direction was set, and no formal ticket tracks the actual migration work. This ticket aims to formalize the effort and track progress.

Backward Compatibility

This is a critical consideration. Many plugins and themes use dashicons-* CSS classes for admin menus, meta boxes, and custom UI. A migration plan should:

  • Maintain the dashicons stylesheet as a deprecated fallback for a defined transition period (multiple major releases).
  • Provide a compatibility layer so that existing dashicons-* class references continue to render correctly, perhaps by mapping them to their SVG equivalents.
  • Document the migration path for plugin and theme developers with clear timelines.

Related Tickets / References

Attachments (1)

dashboard-widget-at-a-glance.png​ (54.1 KB ) - added by ocean90 3 weeks ago.

Download all attachments as: .zip

Change History (140)

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


5 months ago

#2 @joedolson
5 months ago

This could have some benefits for accessibility, although issues like screen reader announcements are largely irrelevant, now that generated content allows for alt attributes in CSS (which is already implemented in the WordPress CSS.)

Support for aria-label is also relatively irrelevant, as that's just an implementation detail which can also be done with font-icons, just in a different way.

However, the performance implementations and the need to continue to extend the icon set are definitely important considerations that should drive this forward.

For accessibility, the font replacement issue is probably the largest benefit.

#3 @lucasmdo
5 months ago

Thanks @joedolson.

#4 @lucasmdo
5 months ago

This ticket will serve as an umbrella ticket. I'll split this ticket into two: sidebar and admin bar (toolbar).

  • #65386: Toolbar: Replace Dashicons icon font with @wordpress/icons SVGs in the admin bar
  • #65387: Sidebar navigation: Replace Dashicons icon font with @wordpress/icons SVGs in the sidebar navigation

#6 @lucasmdo
5 months ago

Thanks @wildworks

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


5 months ago

#8 @fushar
5 months ago

This ticket will serve as an umbrella ticket. I'll split this ticket into two: sidebar and admin bar (toolbar).

So I tried updating only the admin bar, but it looks jarring/unbalanced with the sidebar if it still shows the old dashicons. So I took a stab on implementing it for both admin bar and sidebar. I'll link the PR below.

This ticket was mentioned in ​PR #12270 on ​WordPress/wordpress-develop by ​@fushar.


5 months ago
#9

  • Keywords has-patch has-unit-tests added; needs-patch removed

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

[!WARNING]
This PR is stacked on top of #12010. Please only review my commit: 6ec651a52b

Also, some icons were not already public, so they need to be made public, maybe as separate Gutenberg PR. See related: ​https://github.com/WordPress/gutenberg/pull/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/grid ❌
Site Name — frontend dashicons-dashboard core/dashboard
Site Name — wp-admin dashicons-admin-home core/home
Edit Site<br>Customize dashicons-admin-appearance<br>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<br>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?
Dashboard dashicons-dashboard core/dashboard
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 ❌
Users dashicons-admin-users core/people
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.
  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
https://github.com/user-attachments/assets/174d5061-0347-4700-b5a0-58179cc9c79f https://github.com/user-attachments/assets/0c594e0c-b591-49d0-874b-89d79b6336c4

### WP Admin - Multisite

Before After
https://github.com/user-attachments/assets/bb0adc12-6365-4901-b669-b6d447e27bdd https://github.com/user-attachments/assets/e6cb7d8f-7158-4c8c-bf5a-3f666cb4886d

### Frontend

Before

https://github.com/user-attachments/assets/370e575e-1abc-4f9c-ab92-eac3842bd3b7

After

https://github.com/user-attachments/assets/a7d78fcc-67b7-40e3-aafe-b241804a7cb5

### Mobile

Before

https://github.com/user-attachments/assets/31ba3531-b266-49fd-b984-278504db502f

After

https://github.com/user-attachments/assets/3c87c056-d05e-4bae-b19a-043b5d26f6a8

## Use of AI Tools

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

​@JeffPaul commented on ​PR #12270:


5 months ago
#10

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 commented on ​PR #12270:


5 months ago
#11

@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. 😄

https://github.com/user-attachments/assets/e6c65b06-d961-4f6a-bd8c-e2f55a17a9b4

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

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

https://github.com/user-attachments/assets/57dc6934-dfbd-4e92-a988-7be0c6bc36e7

​@tyxla commented on ​PR #12270:


5 months ago
#12

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 commented on ​PR #12270:


5 months ago
#13

@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 commented on ​PR #12270:


4 months ago
#14

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: ​https://github.com/WordPress/gutenberg/pull/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!

​@fcoveram commented on ​PR #12270:


4 months ago
#15

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
https://github.com/user-attachments/assets/2cea23a8-e9f4-4c32-a62f-e8820657331a https://github.com/user-attachments/assets/3919ffc6-a3e1-459e-a5ce-860d47095c92

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 commented on ​PR #12270:


4 months ago
#16

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 commented on ​PR #12270:


4 months ago
#17

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 commented on ​PR #12270:


4 months ago
#18

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:

https://github.com/user-attachments/assets/a1c24c8d-ab14-4aca-8fae-d0e48e1f58ed

​@fushar commented on ​PR #12270:


4 months ago
#19

@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:

https://github.com/user-attachments/assets/65924104-8433-44c3-9fce-7aa8a48a9972

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 commented on ​PR #12270:


4 months ago
#20

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 ​https://github.com/WordPress/gutenberg/pull/79451#issuecomment-4797981729.
    • @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 rending 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.

​@wildworks commented on ​PR #12270:


4 months ago
#21

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 commented on ​PR #12270:


4 months ago
#22

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 commented on ​PR #12270:


4 months ago
#23

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.

​@wildworks commented on ​PR #12270:


4 months ago
#24

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 commented on ​PR #12270:


4 months ago
#25

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 commented on ​PR #12270:


4 months ago
#26

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.

​@tyxla commented on ​PR #12270:


4 months ago
#27

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.

​@Joen commented on ​PR #12270:


4 months ago
#28

Noting that I designed a "Sites" icon here: ​https://github.com/WordPress/gutenberg/pull/80094

​@mcsf commented on ​PR #12270:


4 months ago
#29

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

I think this would defeat the purpose of introducing SVG icons to finally move away from Dashicons! Then we'd have to support both systems forever.

I like Marin's argument below. Currently it seems like the wisest choice to me:

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.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 months ago

​@Joen commented on ​PR #12270:


2 months ago
#31

Coming back to this one, the Verse icon is growing on me for posts. I also tried the cog for settings, the single image for media, the single page for pages, and in ​https://github.com/WordPress/gutenberg/issues/81274 I tried a new "tool" icon that could eventually benefit this effort.

https://github.com/user-attachments/assets/90a76fe4-e974-4da6-b837-7e5ff0958e57

#32 @Joen
2 months ago

Noting that I created ​https://make.wordpress.org/core/2026/09/04/replacing-dashicons-in-the-admin-bar-and-menu/ to help bring more visibility to this issue.

​@fushar commented on ​PR #12270:


2 months ago
#33

All right, after the dust settled for 7.1, I rebased updated the PR as follows:

  • Use default 24px size for the icons
  • Use the new core/sites for My Sites.
  • Use core/verse for Posts.
  • Use core/cog for Settings.

I updated the screenshots in this PR to reflect the latest.

We still need to decide how to use the currently-private icons; it's still unresolved discussion.

​@fushar commented on ​PR #12270:


2 months ago
#34

Also, if we want to make this a Gutenberg experiment, we need to at least ship this diff in Core, to allow using core icons in the sidebar. Curious to hear what others think.

https://github.com/user-attachments/assets/cece69fe-2ba3-450c-978e-e84d5579d4d2

​@Joen commented on ​PR #12270:


2 months ago
#35

Not a strong opinion, but I don't think this should be a Gutenberg experiment. It seems worth merging early in the cycle, and then evaluating feedback from that.

​@afercia commented on ​PR #12270:


2 months ago
#36

When running npm install on this branch, it hangs for minutes for me with this message. Is it just me?

npm warn deprecated svgo@1.3.2: This SVGO version is no longer supported. Upgrade to v2.x.x.
npm notice This endpoint is being retired. Use the bulk advisory endpoint instead. See the following docs for more info: https://api-docs.npmjs.com/#tag/Audit

​@ugyensupport commented on ​PR #12270:


2 months ago
#37

Tested locally against a WP 7.1 (trunk-level) install, both commits applied.

The PR's code works correctly against core alone — verified via wp eval that wp_get_icon('core/tool') and the other 11 new icons all return proper SVG markup, and confirmed visually (WP logo, Media, Pages, Appearance, Plugins, Tools, Settings all render the new inline SVGs correctly in the admin bar and sidebar, desktop and mobile breakpoints). The core/people no-avatar fallback and the mirrored search icon also behave as described in the PR.

Heads-up for anyone else testing locally with the Gutenberg plugin active, though: Gutenberg ships its own WP_Icons_Registry_Gutenberg shim (lib/class-wp-icons-registry-gutenberg.php) that replaces core's WP_Icons_Registry singleton with a registry pre-loaded from Gutenberg's own (currently stale) icon set. Core's _wp_register_default_icons() still runs, but registration of this PR's 12 new icons silently no-ops via _doing_it_wrong( 'WP_Icons_Registry_Gutenberg::register', 'Icon is already registered.' ) wherever the name collides with something Gutenberg already claimed under core/*. Net effect with Gutenberg active: wp_get_icon() returns '' for all 12 new icons, so the WP logo/Media/Pages/Appearance/Settings icons all render blank, and the sidebar's <img> fallback path (wp-admin/menu-header.php) additionally throws a console error per item (net::ERR_NAME_NOT_RESOLVED @ http://core/tool, etc., since esc_url('core/tool') resolves as a protocol-relative host).

This isn't a bug in the PR — deactivating Gutenberg makes every icon render correctly immediately — but since most contributors run Gutenberg locally, it's easy to mistake for one. Worth a note somewhere (or something Gutenberg's own compat shim will need to catch up on before/when this lands).

Screenshots (before / after / after-with-Gutenberg-active-showing-the-blank-icons) and full write-up: available on request, not attached here to keep this comment focused.

🤖 Generated with ​Claude Code

​@afercia commented on ​PR #12270:


2 months ago
#38

A note on the wp_get_icon() function: the handling of the focusable="false" can be entirely removed. That attribute was originally introduced as a workaround for an Internet Explorer bug. IE made any SVG icon within a link focusable so there were two tab stops when tabbing through linked buttons that contained an icon.
Given IE is no longer supported, as far as I can tell the focusable="false" attrirbute is no longer necessary.
Cc @joedolson

​@ugyensupport commented on ​PR #12270:


2 months ago
#39

Before/after screenshots from the local testing above (Gutenberg deactivated, so the PR's icons render as intended):

Before (Dashicons)
https://raw.githubusercontent.com/dugyen/pr12270-icon-test-screenshots/1b98c039e5eeb8e1a4b992cd6c16025adf10b978/pr12270-before-desktop.png

After (@wordpress/icons SVGs)
https://raw.githubusercontent.com/dugyen/pr12270-icon-test-screenshots/1b98c039e5eeb8e1a4b992cd6c16025adf10b978/pr12270-after-desktop.png

🤖 Generated with ​Claude Code

#40 follow-up: @threadi
2 months ago

Great idea, and I'm already looking forward to seeing it implemented. As a plugin developer, I use Dashicons a lot, of course. So I would appreciate it if you could implement

Provide a compatibility layer so that existing dashicons-* class references continue to render correctly, perhaps by mapping them to their SVG equivalents.

and also include instructions on how to use the new icons in CSS instead of the old ones.

Looking forward to hearing more about this :)

#41 in reply to: ↑ 40 @fushar
2 months ago

Replying to threadi:

As a plugin developer, I use Dashicons a lot, of course. So I would appreciate it if you could implement

Provide a compatibility layer so that existing dashicons-* class references continue to render correctly, perhaps by mapping them to their SVG equivalents.

Howdy! The idea is that this is backwards-compatible; so the existing dashicons-* will still work and render the original Dashicons as-is (without any mapping). Hope this helps!

#42 @Joen
2 months ago

include instructions on how to use the new icons in CSS instead of the old ones.

Good question. The recommended path would be to call wp_get_icon():

echo wp_get_icon( 'core/category', array(
	'label' => __( 'Categories', 'my-plugin' ),
) );

This outputs the icon inline. You can find see the full set, with names, ​here. That page also shows which icons are currently public, which are the ones available to insert at the moment, but more are being made public.

A pure CSS method is not something I've dug deep into quite yet, but after the PR lands, some options should be possible. Something like:

.my-plugin-thing::before {
	content: "";
	display: block;
	width: 24px;
	height: 24px;
	background-color: currentColor;
	-webkit-mask: url(/wp-includes/images/icon-library/category.svg) center / contain no-repeat;
	mask: url(/wp-includes/images/icon-library/category.svg) center / contain no-repeat;
}

That could get into CORS trouble and fail across domains. An extreme way that should be theoretically possible but probably avoided would be something along these lines:

add_action( 'admin_enqueue_scripts', function () {
	$icons = array( 'category', 'cog' );   // only what you actually use
	$props = '';

	foreach ( $icons as $name ) {
		$file = ABSPATH . "wp-includes/images/icon-library/{$name}.svg";
		if ( ! is_readable( $file ) ) {
			continue;
		}
		$svg = preg_replace( '/\s+/', ' ', trim( file_get_contents( $file ) ) );
		$uri = 'data:image/svg+xml,' . strtr(
			rawurlencode( $svg ),
			array( '%20' => ' ', '%3D' => '=', '%3A' => ':', '%2F' => '/' )
		);
		$props .= "--wp-icon-{$name}:url(\"{$uri}\");";
	}

	wp_add_inline_style( 'my-plugin-admin', ":root{{$props}}" );
} );

That could theoretically, but this unverified on my part, let you do something like this:

.my-plugin-icon {
	display: inline-block;
	width: 24px;
	height: 24px;
	background-color: currentColor;
	-webkit-mask: var(--wp-icon-category) center / contain no-repeat;
	mask: var(--wp-icon-category) center / contain no-repeat;
}

I would note all of this is me tinkering with PHP and CSS. I'm not recommending using it this way, and it should not be the official way to do it. Hope that helps.

#43 @awetz583
2 months ago

Overall I like this direction. One nit is that the new "brush" icon is difficult to distinguish as the Appearance icon. I feel the "styles" (half filled circle) may be a better fit.

#44 @n8finch
2 months ago

I would agree with @awetz583 that the brush is difficult to distinguish for the Appearance menu item... I would personally opt for desktop (laptop) icon, since it's not just Styles, but also the Editor and Fonts.

That said, everything looks really sharp, great improvements 👏

​@Joen commented on ​PR #12270:


2 months ago
#45

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

| https://github.com/user-attachments/assets/d3b919da-63bd-4996-bd29-2cae874be5ad | https://github.com/user-attachments/assets/eed65a96-1ca1-4ab2-a996-0a934367afae |

  • 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

| https://github.com/user-attachments/assets/11724501-2f83-48ec-a298-ab4137e08f1d | https://github.com/user-attachments/assets/571d1074-f3f4-4942-b338-101859eb2209 |

  • 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:

https://github.com/user-attachments/assets/e1b2a3e0-b226-472f-aa1e-c02f74da54a6

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.

<details><summary>View</summary>

https://github.com/user-attachments/assets/7bc10dcb-422b-4986-83e0-8a769088238c

</details>

​@mrwweb commented on ​PR #12270:


2 months ago
#46

@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 commented on ​PR #12270:


2 months ago
#47

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?

​@Joen commented on ​PR #12270:


2 months ago
#48

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?

#49 @audrasjb
2 months ago

  • Keywords needs-docs needs-user-docs needs-dev-note add-to-field-guide added

We'll need to document this change (with both a dev note, and also end user docs) and update a good amount of existing docs (screenshots… ugh 😅).

Therefore I'm adding some useful keywords to the ticket :)

​@fushar commented on ​PR #12270:


2 months ago
#50

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

@jeffpaul It looks like this 🙂

BeforeAfter
https://github.com/user-attachments/assets/b38542a9-5e99-4bbe-ace5-54444498dab2 https://github.com/user-attachments/assets/e6d02d91-66c5-49a6-a58e-a9d410f06543

​@fushar commented on ​PR #12270:


2 months ago
#51

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.

​@Joen commented on ​PR #12270:


2 months ago
#52

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

​@fushar commented on ​PR #12270:


2 months ago
#53

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 🙂

​@ugyensupport commented on ​PR #12270:


2 months ago
#54

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 commented on ​PR #12270:


2 months ago
#55

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

​@wildworks commented on ​PR #12270:


8 weeks ago
#56

@fushar, thank you for working on this, and I apologize for the delayed reply.

The biggest concern with moving this PR forward is that the core icon collection could be unregistered by consumers. If a consumer were to use code like the following—for example, to hide core icons in the Icon block—all the dashboard menu icons would disappear. I don't think the dashboard icon should disappear under any circumstances.

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

https://github.com/user-attachments/assets/a1ab23b0-9f32-422a-9b85-949df5b846c9

Perhaps we should add a non-deletable _builtin icon collection, and any icons related to the dashboard should be included in that collection. This idea has already been proposed in ​https://github.com/WordPress/wordpress-develop/pull/12270#issuecomment-4864984947. This approach is similar to how ​post types and ​post taxonomies are handled.

​@ugyensupport commented on ​PR #12270:


8 weeks ago
#57

@t-hamano I re-tested this against the Playground link in the PR description (core PR #12270 + ​gutenberg#79451) and can confirm the concern — it's a clean, one-line reproduction:

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

Before: wp_get_icon( 'core/pin' ) returns valid SVG, 99 icons registered under the core collection.
After the snippet runs: wp_get_icon( 'core/pin' ) returns '', 0 collections and 0 icons remain registered. Every admin-bar and sidebar icon disappears on /wp-admin/ — WP logo, +New, Comments, avatar, Dashboard, Posts, Media, Pages, Comments, Appearance, Plugins, Users, Tools, Settings, all gone. Removing the mu-plugin restores them immediately, confirming it's the unregister call.

Root cause is in the already-merged registry classes, not in this diff: WP_Icon_Collections_Registry::unregister() (​class-wp-icon-collections-registry.php) and WP_Icons_Registry::unregister() (​class-wp-icons-registry.php) have no protection for the core collection/icons, and this PR is what makes core chrome newly depend on that same collection.

+1 on the _builtin approach from ​#12270 (comment), mirrored on ​`unregister_post_type()`. Concretely, in icons.php/class-wp-icon-collections-registry.php/class-wp-icons-registry.php:

  1. Mark the core collection _builtin => true when _wp_register_default_icon_collections() registers it — but keep that flag internal (not part of the public label/description $allowed_keys in WP_Icon_Collections_Registry::register()), so a plugin can't declare its *own* collection built-in and make it un-removable too.
  2. Guard both unregister() methods:
    // WP_Icon_Collections_Registry::unregister()
       if ( ! empty( $this->registered_collections[ $collection_slug ]['_builtin'] ) ) {
           _doing_it_wrong( __METHOD__, __( 'Unregistering a built-in icon collection is not allowed.' ), '7.1.0' );
           return false;
       }
    
// WP_Icons_Registry::unregister()
   $collection = WP_Icon_Collections_Registry::get_instance()->get_registered( $this->registered_icons[ $icon_name ]['collection'] );
   if ( ! empty( $collection['_builtin'] ) ) {
       _doing_it_wrong( __METHOD__, __( 'Unregistering a built-in icon is not allowed.' ), '7.1.0' );
       return false;
   }

The second guard matters on its own — without it a consumer can still pick off individual core/* icons one at a time via wp_unregister_icon() even with the collection protected.

  1. Add coverage in tests/phpunit/tests/icons/wpIconCollectionsRegistry.php and wpIconsRegistry.php asserting both unregister calls return false and leave the registry untouched for core, plus a case that a plugin can't smuggle _builtin => true onto its own collection.

Since the registry classes are already in trunk, this would need its own small companion PR/ticket rather than living in this diff — happy to help put that together if useful. Screenshots of the before/after repro available if helpful.

​@ugyensupport commented on ​PR #12270:


8 weeks ago
#58

Screenshots from a repro of the above, on the Playground link in the PR description (core PR #12270 + gutenberg#79451):

Before — normal dashboard, all icons render:
https://github.com/user-attachments/assets/bf0cb176-b6f8-4127-992e-0db10f21057c

After — same site, after an mu-plugin runs the exact snippet quoted above (wp_unregister_icon_collection('core') on init, priority 20). Every admin-bar and sidebar icon disappears — WP logo, +New, Comments, avatar, and the entire left menu:
https://github.com/user-attachments/assets/0bca9f1e-2775-4726-8487-3add48026872

Removing the mu-plugin restores them immediately, confirming it's the unregister call.

​@mrwweb commented on ​PR #12270:


8 weeks ago
#59

Does preventing unregistering the icon in the admin also prevent unregistering the Core icon set in the Icon Block? If so, I think that would be a problem for a lot of customized sites.

Glancing at the snippets above would seem to suggest it applies to all contexts. Sorry that I don't have time to test this right now, but I just want to make sure. It'll still be important that developers can provide and limit icons in the Icon block to a single custom set that does not include the Core set.

​@wildworks commented on ​PR #12270:


7 weeks ago
#60

I have submitted ​https://github.com/WordPress/gutenberg/pull/83012, which proposes adding a built-in icon set that cannot be unregistered internally, separate from the core icon collection.

​@mcsf commented on ​PR #12270:


7 weeks ago
#61

@dugyen: let's avoid the LLM replies, please. See our emerging ​AI guidelines. Honest contributions from a human are welcome, especially in the form of proper testing, use-case feedback, and novel suggestions; everything else is verbiage and a distraction.

​@fushar commented on ​PR #12270:


7 weeks ago
#62

The biggest concern with moving this PR forward is that the core icon collection could be unregistered by consumers. If a consumer were to use code like the following—for example, to hide core icons in the Icon block—all the dashboard menu icons would disappear. I don't think the dashboard icon should disappear under any circumstances.

Perhaps we should add a non-deletable _builtin icon collection, and any icons related to the dashboard should be included in that collection. This idea has already been proposed in ​https://github.com/WordPress/wordpress-develop/pull/12270#issuecomment-4864984947. This approach is similar to how ​post types and ​post taxonomies are handled.

Thanks @t-hamano and sorry for the delayed response as I am supposed to be on vacation this week 😄 Somehow, I missed this discussion as it was long time ago 🤦

I have submitted ​WordPress/gutenberg#83012, which proposes adding a built-in icon set that cannot be unregistered internally, separate from the core icon collection.

It's an interesting approach. However, it seems to exclusively works with core (WordPress) icons. I think your concerns can also be applied to plugins. For example, what if e.g. Font Awesome also registers some public: false icons to show icons in the admin bar or menus (for its plugin itself)? Now other plugins or certain admins cannot unregister the collection without also making the icons in the admin bar or menus suddenly disappear.

I am proposing two new approaches:

  1. If an icon is public: false, allow it to render via wp_get_icon() even though the collection itself is unregistered.
  2. Or, have a separate collection for admin screens. For instance, core-admin/, or font-awesome-admin/. Those icons are not supposed to be offered in the Icon block, thus all icons inside them should be public: false. The collections can still be unregistered, but it's a questionable decision by extenders.
    • when doing gutenberg_register_default_icons(), if public: false in the manifest, we also register the icon to core-admin/.

Thoughts?

​@mcsf commented on ​PR #12270:


7 weeks ago
#63

It's an interesting approach. However, it seems to exclusively works with core (WordPress) icons. I think your concerns can also be applied to plugins. For example, what if e.g. Font Awesome also registers some public: false icons to show icons in the admin bar or menus (for its plugin itself)? Now other plugins or certain admins cannot unregister the collection without also making the icons in the admin bar or menus suddenly disappear.

I completely understand the worry here, but my intuition tells me that we should think of this as two separate concerns:

  • Built-in icons are really critical, because we don't want WP-Admin standard icons to ever degrade to some kind of fallback
  • Third-party menus and other pieces of plugin code may certainly consider some icons to be "critical" for them, but the hackable nature of WordPress is such that filters may have been added/removed, icons may have been edited, and so all third-party code must be somewhat defensive. Yes, it would annoying if the admin icon for Plugin X were suddenly missing, but the alternative would be to prevent other third parties from ever filtering Plugin X's data, which IMO would go against WP's spirit of extensibility. WDYT?

Also, a reminder that, whatever solution we adopt, it should not break Gutenberg's ability to override Core icons. I know, I know, this looks a bit like a double standard. 😄

​@Joen commented on ​PR #12270:


7 weeks ago
#64

Noting, better late than never, that there's a PR here to update and add new icons based on the discussion here: ​https://github.com/WordPress/gutenberg/pull/83338

​@fushar commented on ​PR #12270:


6 weeks ago
#65

I updated this PR based on the recently-merged GB PRs:

I also updated the images in the PR description to reflect the latest state. This PR can now be tested on: ​https://playground.wordpress.net/?core-pr=12270&gutenberg-branch=trunk 🙂

​@fushar commented on ​PR #12270:


5 weeks ago
#66

@t-hamano / @desrosj, now that Gutenberg 24.1 is released, could you help syncing it to Core trunk, so that I can rebase this PR and (finally!) test it properly? 🥹

​@fushar commented on ​PR #12270:


5 weeks ago
#67

I've pushed two minor changes

Thanks for the changes, those look good to me!

As I understand it, this PR depends on a couple of tasks

Ah yep, you're right, we need the backport PR as well. I forgot about that because PR also seems to work just with GB 24.1 installed as plugin with the Playground link I mentioned above. It seems that PR is already approved.

​@wildworks commented on ​PR #12270:


4 weeks ago
#68

  1. Sync changes from Gutenberg 24.1: This will sync the latest icon manifest file to Core. The manifest file includes a collections property to distinguish between core and core-admin collections. See ​https://github.com/WordPress/gutenberg/pull/83261/.
  2. Commit ​https://github.com/WordPress/wordpress-develop/pull/13625. This will register the non-public core-admin collection directly into Core itself.

@fushar, I've finished these tasks. We should be able to test this PR without Gutenberg once it is updated.

​@fushar commented on ​PR #12270:


4 weeks ago
#69

Thanks @t-hamano!

I rebased and retested this PR:

  • tested using multiple other plugins to check backward compatibility
  • tested mobile and desktop resolutions
  • tested with admin color schemes
  • tested multi-site installations

Seems to working well. This PR is ready for final review I think 🙂

​lucasmendes-design commented on ​PR #12270:


4 weeks ago
#70

I've spent some time testing the icons on many different contexts and situations. My feedback is not blocker is just an enhancement we must do in the future or if it's possible now. It's amazing to see the WP Admin with the new icons and it's already way better than before. It feels more modern and clean :)

Following up on @jasmussen's stroke weight test, I believe we have a case for it on mobile. This comment shows the problem and a small fix.

Currently, the mobile breakpoint grows the admin bar icons from 24px to 34px. However, every Core icon has vector-effect="non-scaling-stroke", so the line stays at 1.5px. The icon is 42% bigger, the stroke is not. In other words, the sidebar icons keep a 1:16 stroke to size ratio and the admin bar drops to 1:22. That is why the admin bar looks thinner than the sidebar on the same screen.

https://github.com/user-attachments/assets/52275a5a-64db-4577-83ed-56b687da0d4a

The fix is one rule inside the existing 782px media query:

#wpadminbar .ab-icon svg {

width: 32px;
height: 32px;
stroke-width: 2;

}

32px with a 2px stroke keeps the same 1:16 ratio as the sidebar and stays on the pixel grid. 34px would need 2.125px, which is not. The W logo is already 32px on mobile, so it aligns as well.

​lucasmendes-design commented on ​PR #12270:


4 weeks ago
#71

Longer term this ratio could live in the icon API as a stroke width option, as discussed in gutenberg#81274. That is a follow-up, not this PR.

​@Joen commented on ​PR #12270:


4 weeks ago
#72

Thanks, there's a trivial fix we can easily land in 7.2 on the icon scaling, if we have to, I'll chat with some folks.

​@fushar commented on ​PR #12270:


4 weeks ago
#73

32px with a 2px stroke keeps the same 1:16 ratio

100c741891f1569378509e54c42de1b0391d0945 + ​https://github.com/WordPress/gutenberg/pull/84081 should fix it 😄

​@fushar commented on ​PR #12270:


4 weeks ago
#74

I am keeping track of unresolved discussions. Stopping here for the day and will continue tomorrow 👍

​@ugyensupport commented on ​PR #12270:


4 weeks ago
#75

Are we very close to merge this build @fushar @tyxla

​@fushar commented on ​PR #12270:


4 weeks ago
#76

My main worry is backward compatibility: many plugins and sites rely on dashicons classes, ::before CSS and dashicons-* values in menu_icon, and this PR can break them without a fallback when an icon is missing.

@tyxla, you're right, I'm now playing around with plugins after scanning veloria, and many break. I'm thinking on some compromises. Please don't re-review backcompat issues as I'm still refining the ideas.

​@fushar commented on ​PR #12270:


4 weeks ago
#77

Hi all. It seems easier to review the backcompat issues by drafting the dev note first, so we can align with the backcompat expectation.

I spent the entire day brainstorming 🙂 the tricky part here is that some admin bar nodes use <span class="ab-icon"> in the title and then use .ab-icon::before in CSS to draw the dashicons. But, some target .ab-item::before directly without additional span in the title. So, any backcompat logic must take these differences into account.

Also it seems, there will be breaking changes no matter what. It is hard to mimic existing ::before rule in CSS and apply it to the SVG, unless we want to use hacky JS. It doesn't seem wise to achieve 100% backcompat.

I've put together my idea and rationale here: ​https://docs.google.com/document/d/1N-Yx8nxQPpVHWZhVuiybHdhJR5D7sl45jX7sCOQ1orA/. Note that the doc is AI-assisted and I might rewrite some parts later, but trust me that I am responsible with the high-level idea and the structure of the doc 😄 Any suggestions welcome.

I pushed an implementation of the idea in the latest commit f7a6e83.

I am still testing locally with various plugins. I will continue testing on Monday. Have a good weekend.

​@fushar commented on ​PR #12270:


4 weeks ago
#78

My own (human) reading of the situation: WordPress never guarantees the stability of DOM or CSS selectors, though historically many plugins depend on them in some way. The breakage happen on plugins that modify the admin bar, and I don't see catastrophic issues. (With the exception of the double icons on My WP Customize Admin/Frontend 1.27.4; we might want to email the plugin author out of courtesy.)

The main issue here is styling on ::before pseudo-element. I don't see a good way to achieve 100% back-compat. Example approaches:

  • Printing the icons as mask in the CSS, which is against the ​original vision.
  • Detecting such rules and recreating the rules for the correct target via JavaScript.

So if we want to move forward with this without hacky approaches above, I believe the most appropriate way forward is to polish and ship this PR, and publish the dev note soon so plugin authors can adapt asap.

​@tyxla commented on ​PR #12270:


4 weeks ago
#79

So if we want to move forward with this without hacky approaches above, I believe the most appropriate way forward is to polish and ship this PR, and publish the dev note soon so plugin authors can adapt asap.

I agree with this. It's the only way we can move forward. So a good next step would be to have a very thorough dev note that helps people with various use cases migrate their code. We should land this sooner so it's part of the 7.2 beta and folks have a good chance to test it. I'm around this week and happy to help with whatever I can to move this forward.

​@fushar commented on ​PR #12270:


4 weeks ago
#80

So a good next step would be to have a very thorough dev note that helps people with various use cases migrate their code.

Yes, that's what I'm trying to capture with the ​draft dev note 😄

I'm around this week and happy to help with whatever I can to move this forward.

Thanks, looking forward to it! Another area to help is the discussion re: performance. I'm still testing and it is a fact that this PR makes wp-admin pages load *slightly* slower, but not sure if we should implement the improvement (whatever it is) here in PR. One possible approach is maybe to hardcode (generate) the core-admin/ SVG strings so that they don't have to be read from disk and validated every time we load wp-admin pages.

​@tyxla commented on ​PR #12270:


4 weeks ago
#81

Another area to help is the discussion re: performance. I'm still testing and it is a fact that this PR makes wp-admin pages load slightly slower, but not sure if we should implement the improvement (whatever it is) here in PR. One possible approach is maybe to hardcode (generate) the core-admin/ SVG strings so that they don't have to be read from disk and validated every time we load wp-admin pages.

Yeah, I don't think it needs to happen in this PR, but it would help to have a few possible explorations / approaches tried out so we can pick the one that is the best compromise. The performance aspect here be something that surely comes up during beta, so we do some of the legwork in draft PRs before actually merging the PR.

​dugyen commented on ​PR #12270:


4 weeks ago
#82

@fushar, my name was unlinked could you please check

​@ugyensupport commented on ​PR #12270:


4 weeks ago
#83

Test Report

Environment

  • WordPress: 7.2-alpha (PR build via Playground)
  • PHP: 7.4.33
  • Browser: Chrome
  • OS: macOS
  • Theme: Twenty Twenty-Five

Results

Core icons

  • ✅ Admin bar (wp-admin): menu, WP logo, home, search, comments and + New render as SVG with aria-hidden="true".
  • ✅ Admin bar (frontend): Site Name shows the dashboard icon, Edit Site the brush, Edit Post the pencil.
  • ✅ Admin menu: all core items render 24px SVGs; Collapse Menu chevron flips when collapsed and the folded menu looks correct.
  • ✅ Mobile (400px): menu toggle, home, search and plus render correctly.
  • ✅ RTL: layout mirrored, collapse chevron points the right way.

Back-compat with plugin icons

Case Result
Unmapped Dashicon (dashicons-chart-pie) ✅ still uses the font icon
CPT with menu_icon => 'dashicons-admin-post' ✅ mapped to the pin SVG
base64 SVG / image URL / 'none' ✅ unchanged
Namespaced icon core/chart-bar (menu page, CPT, admin bar icon arg) ✅ renders as SVG
Admin bar node with <span class="ab-icon dashicons dashicons-star-filled"> ✅ icon shows
Admin bar node with .ab-icon:before { content: "\f155" } ✅ icon shows
Unregistered icon (core/does-not-exist) ✅ empty slot + _doing_it_wrong notice

Color schemes

  • ✅ In all 9 core schemes, the computed color of the SVG menu icons matches the Dashicons menu icons exactly (base and current states), and admin bar icons match too.
  • ✅ A custom scheme registered with its own stylesheet and icons colors gets the new inline rules applied (base and current colors correct).

Notes

  • Minor: an admin bar node with an unregistered icon still outputs an empty 24px .ab-icon.svg-icon span plus margin, leaving a visible gap before the title. The admin menu outputs nothing in the same case — skipping the wrapper when wp_get_icon() returns an empty string might be cleaner.
  • The only failing check, "Upgrade from 7.1 / PHP 8.4 with MySQL 8.4 multisite", is a network timeout downloading wordpress-7.1.tar.gz, unrelated to this PR.
  • Not tested: multisite (My Sites / blavatar) and the live color-scheme preview on the profile screen.

​@fushar commented on ​PR #12270:


4 weeks ago
#84

Thanks @t-hamano for reviewing and resolving GitHub comments, I'll continue tomorrow!

​@fcoveram commented on ​PR #12270:


4 weeks ago
#85

Chiming in with a design review. Feel free to dismiss these thoughts if this isn't timely.

Stroke width on mobile

With the stroke scaling work (​Gutenberg#84081), the 32px size becomes bolder. I see that non-scaling-stroke is still there, so a follow-up would be to find a coherent way to use icons that keeps the stroke width the same in both the admin bar and the sidebar.

WordPress icon scale

The WordPress icon looks slightly bigger because it uses 20 of the 24 units in its container. Until the icon becomes stroke-based, perhaps we can scale it to 18px inside the same 24px container. This also relates to #84105.

Search icon orientation

The new search icon faces the opposite way, and SearchableSelectControl already shows it. I'd flip it horizontally to match the search icon in the Command Palette until the latter inherits the new design. This is only an interim solution so the user flow for triggering the CP doesn't feel visually clumsy.

​@fushar commented on ​PR #12270:


4 weeks ago
#86

The WordPress icon looks slightly bigger

But isn't this also the case with Dashicons before this PR? I thought that's intended 😄 the W's circle before and after this PR has the same size I believe.

​@fcoveram commented on ​PR #12270:


4 weeks ago
#87

But isn't this also the case with Dashicons before this PR? I thought that's intended 😄 the W's circle before and after this PR has the same size I believe.

I don't know what structure Dashicons followed, and the current SVG exceeds the grid. It is definitely a design problem, but the solution is tricky, as logos scale proportionally and the ring that wraps the W symbol does as well.

​@fushar commented on ​PR #12270:


3 weeks ago
#88

Search icon orientation

The new search icon faces the opposite way, and SearchableSelectControl already shows it. I'd flip it horizontally to match the search icon in the Command Palette until the latter inherits the new design. This is only an interim solution so the user flow for triggering the CP doesn't feel visually clumsy.

Hmm, what about the frontend search icon (the one in top-right), do we want to flip that as well?

Also, wouldn't it be much easier and consistent if we flip the one in the command palette modal instead? Then everything will match new new search icon?

​@fushar commented on ​PR #12270:


3 weeks ago
#89

WordPress icon scale

Until the icon becomes stroke-based

I'd defer this to @jasmussen because I read the idea is to NOT make wordpress icon stroke-based as per ​https://github.com/WordPress/gutenberg/issues/81274#issuecomment-5989357989.

​@fushar commented on ​PR #12270:


3 weeks ago
#90

I made a few iterations to the ​draft dev note. I believe it's now in a good shape.

I ran this with my Opus 5.5 agent (which had access to a working local WordPress dev server) and it verified the claims 🙂

The next step would be to agree on the direction of the back-compat strategy mentioned in the dev note.

​@fcoveram commented on ​PR #12270:


3 weeks ago
#91

Hmm, what about the frontend search icon (the one in top-right), do we want to flip that as well?

I don't see a reason as the input visible after clicking on the icon shows the same orientation.

Also, wouldn't it be much easier and consistent if we flip the one in the command palette modal instead? Then everything will match new new search icon?

Not sure if it's easier, but coherent for sure. I'm not aware of the timelines and plans for the CP and whether this change is doable before the deadline. So pinging @senadir as his input is relevant here.

​@wildworks commented on ​PR #12270:


3 weeks ago
#92

The orientation of the search icon has been discussed a few times before. See ​https://github.com/WordPress/gutenberg/pull/72070. My understanding is that in LTR languages, the search icon should face left.

So the search icon in the Command Palette should be facing the correct direction:

https://github.com/user-attachments/assets/1b389b02-9e2d-455c-a665-680c2c6c9197

I think the ones that need fixing are SearchableSelectControl, the admin bar in the admin, and the admin bar on the front end.

Component Screenshot
SearchableSelectControl https://github.com/user-attachments/assets/907460e0-f7dd-446d-8540-2655e80e3340
Admin bar (admin) https://github.com/user-attachments/assets/36379ec8-dbb9-40a7-86be-816c10c57fd0
Admin bar (front end) https://github.com/user-attachments/assets/539ef0e9-ba0b-4f9e-a01a-102a38fbedb9

cc @WordPress/gutenberg-components

​@fushar commented on ​PR #12270:


3 weeks ago
#93

Thanks for the additional context 😄 the search icon direction is now fixed in the latest commit 6c3fc8b059641be15c5512a519fff4e43b51cf9c.

​@fcoveram commented on ​PR #12270:


3 weeks ago
#94

The icon direction looks correct now ✨

​@fushar commented on ​PR #12270:


3 weeks ago
#95

@peterwilsoncc Let's discuss ​your comment here instead of on the diff. GitHub UI is bad for PRs with many comments; it's hard to follow chronological discussion 😅

Reading the comment, I think there's a bit a more fundamental issue here. If plugins want to "migrate" their dashicons to SVG icons, should we tell them to use core-admin/ or core/ collection? Both have issues:

  • If they're supposed to use core-admin/ only, the collection currently only has few icons, because the set was meant to contain only Core's built-in icons.
  • If they may use core/, then they won't survive when the core/ collection is unregistered. See the discussion in the ​original PR, the main idea being that we don't want the icons in the admin screens to be unregisterable at all.

I'm thinking a few approaches here:

  1. Expand core-admin/ collection to have a few more "popular" icons from core/.
  2. Or just simply make core-admin/ a proper superset of core/.
  • And we might optionally ban core/ from being used when constructing the sidebar menu and admin bar nodes. (Not sure)

Sorry, I just realized about this now. I might be overthinking, but the potential confusion is real here.

Thoughts @t-hamano, @tyxla, @mcsf ?

​@wildworks commented on ​PR #12270:


3 weeks ago
#96

Reading the comment, I think there's a bit a more fundamental issue here. If plugins want to "migrate" their dashicons to SVG icons, should we tell them to use core-admin/ or core/ collection? Both have issues:

  • If they're supposed to use core-admin/ only, the collection currently only has few icons, because the set was meant to contain only Core's built-in icons.
  • If they may use core/, then they won't survive when the core/ collection is unregistered. See the discussion in the ​original PR, the main idea being that we don't want the icons in the admin screens to be unregisterable at all.

@fushar Thanks for raising this. I agree that your concern is valid.

Here are my thoughts and suggestions:

  • core-admin is still the collection for wp-admin, while core is the collection for the front end, content, and the Icon block.
  • Don't automatically migrate Dashicons to SVG icons at all. It's not possible to map every Dashicon one-to-one to an SVG icon in the first place. The only exception is the core menu items, which are migrated to SVG icons (third-party items are not).
  • Let consumers know the following through the dev note:
    • Encourage them to use SVG icons instead of Dashicons where possible when registering menus and post types.
    • Publish the list of icons currently available in the core-admin collection.
  • Expand the core-admin icons as much as possible, based on requests from developers or as a follow-up.

I tried installing a lot of plugins, and personally, I don't find the mix of SVG icons and Dashicons that jarring. What do you think?
https://github.com/user-attachments/assets/5daa497a-c287-470a-b221-1b3b59ad3093

​@fushar commented on ​PR #12270:


3 weeks ago
#97

Thanks @t-hamano I agree with all your suggestions. They make sense to me. Particulary:

I tried installing a lot of plugins, and personally, I don't find the mix of SVG icons and Dashicons that jarring.

Yep, I agree. I know that @jasmussen et al have designed the icons in such a way that they don't look too out of place compared to the original Dashicons 🙂

Let consumers know the following through the dev note

I'll add that to the dev note.

Expand the core-admin icons as much as possible

Yeah, agree. I think we should add more generic icons, like envelope, cart, etc. That would need to happen on Gutenberg first (I can try to raise the PR). WDYT @jasmussen?

​@tyxla commented on ​PR #12270:


3 weeks ago
#98

I agree with @t-hamano's plan, including not auto-mapping third-party dashicons, with a few small notes:

  • If the dev note tells plugins to use core-admin/*, those icons become public API, even with public => false. We'll likely want to say this clearly in the dev note and the wp_register_icon() docs. We'll also have to agree that we never rename or remove an icon once it's added.
  • Worth mentioning in the dev note that plugins can register their own collection (like my-plugin/cart). It already works in menus and the admin bar.
  • I'd prefer not banning public collections. New collections are public by default, so a ban would also block plugin icons and adding unnecessarily limits.

​@fushar commented on ​PR #12270:


3 weeks ago
#99

Stroke width on mobile
With the stroke scaling work (​https://github.com/WordPress/gutenberg/pull/84081), the 32px size becomes bolder. I see that non-scaling-stroke is still there, so a follow-up would be to find a coherent way to use icons that keeps the stroke width the same in both the admin bar and the sidebar.

WordPress icon scale
The WordPress icon looks slightly bigger because it uses 20 of the 24 units in its container. Until the icon becomes stroke-based, perhaps we can scale it to 18px inside the same 24px container. This also relates to ​https://github.com/WordPress/gutenberg/pull/84105.

I wonder if we can approach it differently and apply an ad hoc property that scales it to 18px inside the same 24px container.

Honestly, I don't fully understand this and this is a bit beyond my expertise 😄 I'd like to defer the implementation details to the icon designers @jasmussen / @lucasmendes-design. We should be able to follow up as separate PR during the Beta if needed.

​@fushar commented on ​PR #12270:


3 weeks ago
#100

Folks, thanks for all the help and feedback for this PR so far. Really appreciate it. As Beta 1 is around the corner, I think we should wrap up this PR soon if we want to include it in 7.2. Based on what I read so far, there's no major blocker. What's left is to have an agreement on the proposed back-compat strategy in the ​dev note, and test its claims. Personally, I've already tested this PR so many times with various plugins / color schemes 🙂

​@peterwilsoncc commented on ​PR #12270:


3 weeks ago
#101

Hey folks, sorry I'd missed the resolutions of the previous comments -- as @fushar said, the GH UI can sometimes be confusing.

Folks, thanks for all the help and feedback for this PR so far. Really appreciate it. As Beta 1 is around the corner, I think we should wrap up this PR soon if we want to include it in 7.2. Based on what I read so far, there's no major blocker. What's left is to have an agreement on the proposed back-compat strategy in the ​dev note, and test its claims. Personally, I've already tested this PR so many times with various plugins / color schemes 🙂

Agreed: this can go in beta 1 and further substitutions discussed and an approach figured out during the beta period.

I do like the idea of including the converted icons in the core group within the core-admin group. The font's name dashicons does imply they are available in the dashboard so it's not an unreasonable assumption that the converted icons will be available in the dash.

It would be good to get the dev note out very shortly after beta 1 so devs in plugin land can provide feedback asap.

#102 @wildworks
3 weeks ago

  • Milestone Awaiting Review → 7.2

It seems we forgot to set the milestone for this ticket to 7.2.

​@fushar commented on ​PR #12270:


3 weeks ago
#103

There are two things I'd like to note, both of which can probably be explored in follow-ups:

Yep, I think they can be followed up later and don't need to block this PR 😄

Thanks for all your reviews!

​@Joen commented on ​PR #12270:


3 weeks ago
#104

Catching up, please let me know if I missed anything, it was Danish ​potato vacation last week.

Yeah, agree. I think we should add more generic icons, like envelope, cart, etc. That would need to happen on Gutenberg first (I can try to raise the PR).

I agree, and yes please open issues, happy to draw. To note, though, envelope and cart both ​exist, same names.

Honestly, I don't fully understand this and this is a bit beyond my expertise 😄 I'd like to defer the implementation details to the icon designers @jasmussen / @lucasmendes-design. We should be able to follow up as separate PR during the Beta if needed.

That's from ​this comment, and I can unpack it: the new icons have flexibility the old ones didn't: we can tweak the stroke-width. There's an ongoing question around whether we should, and even how we tweak it if we do. All of that, honestly I'm increasingly leaning towards the instincts of Fran, Aki, @jameskoster and @ciampo on the precise details.

What we do, if anything, in this iteration, I think should not overall affect what we do with this branch: one of the benefits of unifying on WordPress icons (which is the overwhelming focus of this branch), is to unify the codebase too, so whatever improvements we make to the core set, including any changes to stroke-scaling behavior for better legibility, will benefit the admin in future iterations too. So I don't know that we should do any local changes here in this branch or not, I lean to whatever is the simplest to let us focus on the shipping. Is that helpful?

#105 @mcsf
3 weeks ago

  • Keywords commit added

​lucasmendes-design commented on ​PR #12270:


3 weeks ago
#106

Catching up as well. I agree with @jasmussen. No icon-specific changes in this branch. Both open design points are library questions, and Core gets the answer when it bumps @wordpress/icons.

#107 @mcsf
3 weeks ago

  • Owner set to mcsf
  • Resolution → fixed
  • Status new → closed

In 64583:

Administration: Replace Dashicons in admin bar and sidebar with wp-icons.

Replace the usage of Dashicons in admin bar and sidebar with @wordpress/icons via the newly-introduced wp_get_icon() function, which outputs an inline SVG to be rendered.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12270.

Props fushar, wildworks, tyxla, mcsf, mciampini, aduth, peterwilsoncc, jeffpaul, fcoveram, keoshi, joen, afercia, ugyensupport, mrwweb.
Fixes #65089.

#108 @fushar
3 weeks ago

Note that I created follow-up tickets based on the discussion in the PR:

  • #66338 Optimization: Skip sanitizing the icons bundled with WordPress
  • #66344 Consider preventing unregistration of the core-admin icon collection

#109 follow-up: @ocean90
3 weeks ago

Shouldn't we also replace the icons in the "At a Glance" dashboard widget?

#110 in reply to: ↑ 109 @fushar
3 weeks ago

Replying to ocean90:

Shouldn't we also replace the icons in the "At a Glance" dashboard widget?

Good catch. I created a follow-up ticket here: #66347.

#111 @sabernhardt
2 weeks ago

#65386 was marked as a duplicate.

This ticket was mentioned in ​PR #14903 on ​WordPress/wordpress-develop by ​@fushar.


12 days ago
#112

Replaces the hard-coded Dashicon list in _wp_menu_output() with a mapping from the icon library manifest, so admin menu items that use a mapped Dashicon, including those of plugins and custom post types, are rendered with the SVG icon.

  • New private _wp_get_admin_icon_name_for_dashicon( $dashicon ), backed by WP_Icons_Registry::get_admin_icon_name_for_dashicon(). It reads the new dashicons property of the core-admin icons in the manifest, and returns, for example, core-admin/pin for dashicons-admin-post, or null when the Dashicon has no mapping or its icon is not registered.
  • _wp_menu_output() calls it in place of its hard-coded list. A Dashicon whose replacement icon is not registered now falls back to the Dashicons font.
  • icon-library-manifest.php adds dashicons to the 36 icons that are already in core-admin. The mapping is maintained in Gutenberg (WordPress/gutenberg#85541), and the next Gutenberg sync replaces this subset with the full mapping.
  • With the Gutenberg plugin active, its registry subclass overrides the method, so the plugin's mapping applies.

Testing Instructions

  1. npm run test:php -- --filter 'Tests_Icons_WpGetAdminIconNameForDashicon|Tests_Admin_WpMenuOutput'
  2. Register a post type with 'menu_icon' => 'dashicons-cart', and check that its admin menu item shows the SVG cart icon. A Dashicon without a mapping, such as dashicons-heart, still shows the Dashicons font icon.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: The code, tests and this description, under my direction.

This ticket was mentioned in ​PR #14974 on ​WordPress/wordpress-develop by ​@wildworks.


11 days ago
#113

Proof of concept: limit the automatic Dashicon-to-SVG replacement to core menu items.

Currently, any menu item that uses one of the Dashicons of the core menu items (e.g. dashicons-admin-post) is rendered as an SVG icon, including plugin menu items and custom post types without a menu_icon. This PR maps the replacements by the ID of the core menu item, and only while the item still uses its default Dashicon. Other menu items keep their Dashicon, and can opt in to an SVG icon by registering an icon name.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Implementation and tests.

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

🤖 Generated with ​Claude Code

​@Mamaduka commented on ​PR #14903:


11 days ago
#114

All checks are passing after 909edaf5d8f30d94b18f5cbd9813368f70dce2e8. Tested the icons and Playground; they render as expected. Going to commit.

#115 @Mamaduka
11 days ago

In 64798:

Administration: Map Dashicons to replacement icons from the icon library manifest.

Introduce the WP_Icons_Registry::get_admin_icon_name_for_dashicon() method, which returns the core-admin icon that replaces a given Dashicon, based on the dashicons property of the icon library manifest. It returns null if the Dashicon has no mapping or its replacement icon is not registered.

Use it in _wp_menu_output() in place of the hard-coded list of core menu item Dashicons. Menu items from plugins and custom post types that use a mapped Dashicon now get the SVG icon too. A Dashicon with no mapping still uses the Dashicons font.

Follow-up to [64583].

Props fushar, mamaduka, peterwilsoncc.
See #65089.

​@Mamaduka commented on ​PR #14974:


11 days ago
#116

Closing in favor of #14903.

This ticket was mentioned in ​PR #14999 on ​WordPress/wordpress-develop by ​@fushar.


11 days ago
#118

Proposed changes

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

This PR proposes to hide .ab-item::before on any node that renders an SVG icon, so only the SVG icon shows.

See the "Change to the unpublished dev note" section below to see how this affect the dev note.

Benefit for plugin authors

Because of this, a plugin can pass the new icon argument and keep drawing a Dashicon on .ab-item::before, without checking the WordPress version:

$wp_admin_bar->add_node(
        array(
                'id'    => 'my-plugin-notes',
                'icon'  => 'core-admin/pin', // Used in 7.2, ignored before.
                'title' => __( 'Notes', 'my-plugin' ),
                'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
        )
);
/* Used before 7.2, hidden in 7.2. */
#wpadminbar #wp-admin-bar-my-plugin-notes > .ab-item::before {
        content: "\f109"; /* dashicons-admin-post */
}
  • Before 7.2: the icon argument is ignored, and the Dashicon is drawn.
  • In 7.2: the SVG icon is drawn, and the Dashicon is hidden.

This is similar to add_menu_page(), where a plugin can keep passing a Dashicon such as dashicons-admin-post, and 7.2 renders its replacement SVG icon (core-admin/pin), without any version check.

add_menu_page(
        __( 'Notes', 'my-plugin' ),
        __( 'Notes', 'my-plugin' ),
        'manage_options',
        'my-plugin-notes',
        'my_plugin_render_notes',
        'dashicons-admin-post' // Dashicon before 7.2, `core-admin/pin` SVG icon in 7.2.
);

Change to unpublished dev note

The draft dev note for the SVG icons (not published yet) currently says:

Replacing an admin bar icon through .ab-item::before

This applies to the admin bar nodes whose icon used to be drawn on .ab-item::before: edit, customize, site-editor, my-sites, site-name and my-account. The icon is now a separate .ab-icon element, so a content set on .ab-item::before no longer replaces it. Your glyph is still drawn, but core's icon is shown as well.

To fix it, set the content on the ::before of the icon element, which takes the place of core's icon.

/* Before */
#wpadminbar #wp-admin-bar-edit > .ab-item::before { content: "\f319"; }
/* After (7.2 only) */
#wpadminbar #wp-admin-bar-edit > .ab-item .ab-icon::before { content: "\f319"; }

To keep the old rule for earlier versions, limit it to links without the icon element. Otherwise both glyphs show.

/* After (works on 7.2 and earlier versions) */
#wpadminbar #wp-admin-bar-edit > .ab-item:not(:has(> .ab-icon))::before { content: "\f319"; }
#wpadminbar #wp-admin-bar-edit > .ab-item .ab-icon::before { content: "\f319"; }

If this PR is accepted, the section will be SIMPLER. It will be updated to:

Replacing an admin bar icon through .ab-item::before

This applies to the admin bar nodes whose icon used to be drawn on .ab-item::before: edit, customize, site-editor, my-sites, site-name and my-account. The icon is now a separate .ab-icon element, so a content set on .ab-item::before no longer replaces it. Your glyph is hidden, and core's icon is shown instead.

To fix it, set the content on the ::before of the icon element, which takes the place of core's icon.

/* Before */
#wpadminbar #wp-admin-bar-edit > .ab-item::before { content: "\f319"; }
/* After (works on 7.2 and earlier versions) */
#wpadminbar #wp-admin-bar-edit > .ab-item::before,
#wpadminbar #wp-admin-bar-edit > .ab-item .ab-icon::before { content: "\f319"; }

Use of AI Tools

Used Claude Opus 5.5 to discuss the approach and implement the change.

​@fushar commented on ​PR #14999:


10 days ago
#119

Thanks for testing, reviewing, and pointing out the handbook page. Addressed the comments 👍

​@fushar commented on ​PR #14999:


9 days ago
#120

@peterwilsoncc: I added the last commit to address @mcsf's ​comment from the previous PR. Let us know what you think.

​@sadmansakibnadvi commented on ​PR #14999:


9 days ago
#121

Tested bd11baf on 7.2-beta3-64990, counting visible icons per toolbar node in Chrome. Way 1 and Way 2 nodes that pass icon go from 2 icons to 1, and a plugin glyph on the core edit node's .ab-item::before is hidden. Nodes without icon, Duplicate Post 4.7 and Password Protected 2.8.5 are unchanged. The unregistered icon case now keeps the original title with no empty wrapper.

Full table on the ticket: https://core.trac.wordpress.org/ticket/65089

​@peterwilsoncc commented on ​PR #14999:


9 days ago
#122

@propsbot add @mcsf

​@peterwilsoncc commented on ​PR #14999:


8 days ago
#123

@fushar I'm seeing a random gap when using an invalid icon name with the dashicon, to my test plugin above I added:

$wp_admin_bar->add_node(
        array(
                'id'    => 'example4',
                'icon'  => 'core-admin/invalid-icon-name',
                'title' => __( 'Example 4', 'my-plugin' ),
                'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
        )
);

and

#wpadminbar #wp-admin-bar-example4 > .ab-item::before {
        content: "\f109"; /* dashicons-admin-post */
}

In the admin bar the dashicon is shown but there is an empty space for the SVG icon that isn't shown as the mark-up includes <span class="ab-icon svg-icon" aria-hidden="true"></span>

https://github.com/user-attachments/assets/28c9d383-c965-4d52-863a-8430f779b1d2

​@fushar commented on ​PR #14999:


8 days ago
#124

I'm seeing a random gap when using an invalid icon name with the dashicon, to my test plugin above I added:

@peterwilsoncc: yeah, it's an edge case. There are two ways to add dashicon in admin bar nodes:

  1. Using CSS on .ab-item::before (your case)
  2. Using empty <span class="ab-icon dashicons-*"></span> in the title. I believe this is more common as this doesn't require enqueuing CSS.

If the dashicon is added using (2), it's already handled in this PR. Your case (1) is the only edge case missing. It's hard to "fix" it because we can't detect the presence of such CSS-added dashicons in PHP side.

If we want to "fix" it, one idea is to hide the empty slot using CSS something like this, but not sure if it's worth it:

/*
 * Dashicons back-compat: when the icon is not registered, an icon drawn on `.ab-item::before` takes the place of
 * the empty icon element instead of showing next to it.
 */
#wpadminbar .ab-item:has(> .ab-icon.svg-icon:empty)::before {
        width: 24px;
        margin-right: -24px;
        text-align: center;
}

What do you think?

I'm sorry that this PR is becoming more complicated... but admin bar logic is already complicated. It seems we can simplify things e.g. using @t-hamano 's CSS but we need to give up some back-compat behaviors. I'll also brainstorm in the meantime.

​@fushar commented on ​PR #14999:


8 days ago
#125

It seems we can simplify things e.g. using @t-hamano 's CSS but we need to give up some back-compat behaviors.

So I believe the complications come from us trying to have back-compat logic for plugins that modify core nodes. Core nodes inconsistently add dashicons using both .ab-item::before and .ab-icon::before, so it's complicated. For example my comment here: ​https://github.com/WordPress/wordpress-develop/pull/14999#discussion_r4420054526

So maybe, if we give up some of that and instead focus on providing a clean way where plugin's add_node() code can work before and after 7.2 (which originally what this PR is trying to do), maybe that results in cleaner logic in core side and is actually a better win?

​@fushar commented on ​PR #14999:


8 days ago
#126

Thanks all for the patience... I think I managed to implement @t-hamano's idea to hide the old dashicon via CSS. But it has one cost: now unregistered icon will show nothing instead of an empty slot wrapper. I think this is acceptable, since we still report on debug with _doing_it_wrong().

Please check the test cases here: ​https://htmlpreview.github.io/?https://github.com/fushar/wordpress-develop/blob/f832b0c4d51b33019381ea23182d0c9a59c061f8/index.html. I think the back-compat behavior is sufficient. The only breakage is when the code manipulates .ab-item::before, but even so it fails gracefully without weird double icons or weird gap.

​@fushar commented on ​PR #14999:


5 days ago
#127

If I understand correctly, what we're aiming for is the same as the admin menu: replace Dashicons with SVG icons in as many scenarios as possible, without forcing developers to write back-compat code.

Yes, that's the goal!

What do you think? Am I missing anything that would affect backward compatibility?

No, you're not missing anything 😄 at this point this really is down to what we want to support for back-compat. For example, with your proposal, the following will break:

  • The $wp_admin_bar->get_nodes() data (especially title of nodes) will change, so plugins that manipulate core node titles assuming the old html markup, will potentially break.
  • "if a plugin calls remove_node() and then re-adds a node with the same ID (such as edit) without the icon argument, the node no longer gets an icon." <- this one will break as mentioned as well.

What's more important is having a way for plugin authors to write code that works across versions as non-complicated as possible. I believe your and my versions already satisfy that requirement. So now this boils down to simpler core code vs better back-compat.

​@wildworks commented on ​PR #14999:


5 days ago
#128

So now this boils down to simpler core code vs better back-compat.

Personally, I prefer starting with a simple approach and iterating based on consumer feedback. Trying to cover every edge case from the beginning overcomplicates the logic, making it harder for consumers to understand the rules. That said, I think either approach could work. Since you know this feature best, I defer to your judgment 🙂

​@fushar commented on ​PR #14999:


5 days ago
#129

Personally, I prefer starting with a simple approach and iterating based on consumer feedback. Trying to cover every edge case from the beginning overcomplicates the logic, making it harder for consumers to understand the rules.

Interesting, this makes sense.

I think I'm starting to like your approach. If we do that, then in 7.2 Core finally have a consistent structure for admin bar nodes (title + icon, except wp-logo which has no text to manipulate in the first place). If we use the logic in this PR, then we have to maintain that complicated logic forever.

Is there still a time to switch to your approach? Is there a time to pivot to another approach in RC if we have more feedback? Also, I've been holding off releasing the dev note until we settle on this backcompat story 🙂

cc: release tech leads @peterwilsoncc, @Mamaduka

​@wildworks commented on ​PR #14999:


5 days ago
#130

If we do that, then in 7.2 Core finally have a consistent structure for admin bar nodes (title + icon, except wp-logo which has no text to manipulate in the first place). If we use the logic in this PR, then we have to maintain that complicated logic forever.

Exactly. My preference is to minimize exceptions as much as possible and start small and simple.

Is there a time to pivot to another approach in RC if we have more feedback?

In my opinion, this should still be possible since we are currently in the beta phase. If time permits, I would like to see either this PR or mine committed by Beta 3, and then make any final adjustments by Beta 4 or RC 1 if necessary.

​@fushar commented on ​PR #14999:


5 days ago
#131

For reference, I regenerated the test case report using Aki's proposal, showing the difference between the existing PR and the proposal: ​https://htmlpreview.github.io/?https://github.com/fushar/wordpress-develop/blob/c54f9f3/compare.html

I added 3 new cases where the back-compat logic would fail below:

https://github.com/user-attachments/assets/7fbda3df-7274-4991-98d0-f676bbebe34a

Everything else is good.

​@wildworks commented on ​PR #14999:


5 days ago
#132

Thanks for the comparison, @fushar!

---

Core node whose title is edited assuming the original empty span.

https://github.com/user-attachments/assets/4d391c14-6384-400d-92d5-26bf91d1efdf

I think this is quite a rare case. Plugins can already replace the title entirely, so I expect very few developers would edit it by relying on the empty span being there.

---

Core node removed and added back, with its title and link copied.
Core node other than wp-logo whose title is replaced by one with no empty span.

https://github.com/user-attachments/assets/0914d206-5002-4b56-8be2-23f3e96d50f4

These two could be solved by putting the SVG icon in the title of the core nodes that had their icon in the title in 7.1. However, it feels odd for core not to use the new icon argument itself while we are promoting it to plugin developers 🤔

Personally, I think these cases are acceptable, and we can cover them in the dev note.

​@fushar commented on ​PR #14999:


4 days ago
#133

However, it feels odd for core not to use the new icon argument itself while we are promoting it to plugin developers

That's actually a good point. 😅

What if we do your simpler patch, then ship Beta 4 + dev note and see if we have feedback?

It seems @peterwilsoncc (who's been quite involved in the feature) is AFK right now to give opinion.

​@wildworks commented on ​PR #14999:


4 days ago
#134

What if we do your simpler patch, then ship Beta 4 + dev note and see if we have feedback?

Personally, I prefer this one 👍

​@wildworks commented on ​PR #14999:


4 days ago
#135

then ship Beta 4

If we can make it in time, I would like to release it in Beta 3 (Tuesday, 3rd at 15:00 UTC).

​@Mamaduka commented on ​PR #14999:


4 days ago
#136

Beta 3 shipped last week with the security release. We'll do beta 4 and 5 instead.

#137 @wildworks
4 days ago

In 65223:

Toolbar: Hide legacy Dashicons when a node has an SVG icon

When an admin bar node has an SVG icon, the Dashicon it draws for earlier WordPress versions is now hidden, whether that Dashicon is an empty icon element in the title or is drawn with CSS on the link. Plugins can therefore pass the icon argument with the same title on 7.2 and earlier versions, without a version check, and an unregistered icon now renders nothing instead of leaving an empty gap.

Core nodes now set their icons with the icon argument instead of an empty icon element in the title, and the title is no longer modified when the node is rendered.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/14999

Follow-up to [64583].

Props fushar, mamaduka, mciampini, mcsf, peterwilsoncc, sadmansakibnadvi, wildworks.
See #65089.

​@peterwilsoncc commented on ​PR #14999:


3 days ago
#138

Merged r65223 / ​https://github.com/WordPress/wordpress-develop/commit/855f071608b92290ddb62e2dbe2548204fc9c3b3

Thanks for looking after this folks, it's looking really good when running my test plugin.

#139 @fushar
2 days ago

  • Keywords has-dev-note added; needs-dev-note removed
Note: See TracTickets for help on using tickets.