Skip to content

Toolbar: Show only the SVG icon when a node also draws a Dashicon - #14999

Closed
fushar wants to merge 8 commits into
WordPress:trunkfrom
fushar:fix/admin-bar-hide-ab-item-before-with-svg-icon
Closed

fushar wants to merge 8 commits into
WordPress:trunkfrom
fushar:fix/admin-bar-hide-ab-item-before-with-svg-icon

Conversation

@fushar

@fushar fushar commented Oct 27, 2026 •

Copy link
Copy Markdown

Proposed changes

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

This PR makes it possible to write admin bar code that works on 7.2 and earlier versions without a version check, and removes the title manipulation from WP_Admin_Bar::_render_item().

  1. CSS: when a node has an SVG icon, hide the Dashicon that it draws for earlier versions, whether that is on .ab-item::before, in an empty <span class="ab-icon">, or on .ab-icon::before of that span.
    • Core's nodes are excluded from the last case, so that a content on .ab-icon::before still takes the place of core's icon.
  2. PHP: the node title is no longer modified. The empty <span class="ab-icon"> stays in the title of core's nodes and is hidden with CSS. WP_HTML_Tag_Processor is only used to check that the span is there, as a node without it still gets no default icon.
  3. PHP: As a tradeoff, _wp_admin_bar_icon() returns an empty string when there is no icon, so an empty wrapper is never rendered. An unregistered icon renders nothing, which fixes the gap reported by @peterwilsoncc.

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

Comparison on 7.1 and 7.2

See this page for all the test cases: https://htmlpreview.github.io/?https://github.com/fushar/wordpress-develop/blob/f832b0c4d51b33019381ea23182d0c9a59c061f8/index.html

Change to unpublished dev note

The draft dev note for the SVG icons (not published yet) has two sections that become simpler.

Show the current and proposed text

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

It 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, 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"; }

2. Supporting earlier versions (admin bar part)

It currently says:

In contrast, the icon argument of WP_Admin_Bar::add_node() is ignored before 7.2. However, an empty <span class="ab-icon dashicons-*"> in the title still renders in 7.2. So, if your plugin does that and wants to also support earlier versions, pass the icon argument and add the Dashicon element to the title only when the new API is not available as follows.

add_action(
    'admin_bar_menu',
    function ( WP_Admin_Bar $wp_admin_bar ) {
        $title = __( 'Orders', 'my-plugin' );

        if ( ! function_exists( 'wp_is_valid_icon_name' ) ) {
            $title = '<span class="ab-icon dashicons-archive" aria-hidden="true"></span>' . $title;
        }

        $wp_admin_bar->add_node(
            array(
                'id'    => 'my-plugin-archive',
                'icon'  => 'my-plugin/archive',
                'title' => $title,
                'href'  => admin_url( 'admin.php?page=my-plugin-archives' ),
            )
        );
    },
    100
);

If this PR is accepted, it will be updated to:

In contrast, the icon argument of WP_Admin_Bar::add_node() is ignored before 7.2. In 7.2, the icon takes the place of the Dashicon that your node draws for earlier versions, so you can pass the icon argument without checking the version:

  • An empty <span class="ab-icon"> in the title is replaced by the icon.
  • A Dashicon drawn on .ab-item::before is hidden.
  • If your stylesheet sets a content on .ab-icon::before, your glyph takes the place of the icon. Limit the rule to .ab-icon:not(.svg-icon)::before, or remove the element from the title and set the content on .ab-item::before instead.
add_action(
    'admin_bar_menu',
    function ( WP_Admin_Bar $wp_admin_bar ) {
        $wp_admin_bar->add_node(
            array(
                'id'    => 'my-plugin-archive',
                'icon'  => 'my-plugin/archive',
                'title' => '<span class="ab-icon dashicons-archive" aria-hidden="true"></span>' . __( 'Orders', 'my-plugin' ),
                'href'  => admin_url( 'admin.php?page=my-plugin-archives' ),
            )
        );
    },
    100
);

Testing

  • New PHPUnit tests: a node with the icon argument renders only the SVG icon in place of an empty icon element (with or without Dashicons classes), keeps an icon element that has content, and keeps the element when the value is not an icon name.
  • Manually checked on 7.1 and on 7.2 with this PR.

Use of AI Tools

Used Claude Opus 5.5 to discuss the approach, survey how plugins draw admin bar icons, and implement and test the change.

A `content` set on `.ab-item::before` no longer replaces the icon of a node that has an SVG icon. Hide it, so that the two icons are not shown side by side.
@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

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

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

Some things to be aware of

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

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

Test this pull request with WordPress Playground.

@fushar fushar changed the title Toolbar: Hide .ab-item::before icons next to SVG icons WP 7.2 SVG Icon DevX improvement: Hide .ab-item::before icons next to SVG icons Oct 27, 2026
@fushar fushar changed the title WP 7.2 SVG Icon DevX improvement: Hide .ab-item::before icons next to SVG icons WP 7.2 SVG Icon devex improvement: Hide .ab-item::before icons next to SVG icons Oct 27, 2026
@fushar fushar changed the title WP 7.2 SVG Icon devex improvement: Hide .ab-item::before icons next to SVG icons Toolbar SVG icon devex improvement: Hide .ab-item::before icons next to SVG icons Oct 27, 2026
@fushar fushar changed the title Toolbar SVG icon devex improvement: Hide .ab-item::before icons next to SVG icons Toolbar: Hide .ab-item::before icons next to SVG icons Oct 27, 2026
@fushar
fushar marked this pull request as ready for review October 27, 2026 12:29
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

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

Props fushar, mcsf, peterwilsoncc, wildworks, mciampini, sadmansakibnadvi, mamaduka.

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@fushar
fushar requested a review from Mamaduka October 27, 2026 14:20
… title.

A node given the `icon` argument now has the first empty `<span class="ab-icon">` in its title replaced by the icon, as core nodes already do. So a node that draws a Dashicon in its title for earlier versions does not also show it next to the SVG icon.
@fushar fushar changed the title Toolbar: Hide .ab-item::before icons next to SVG icons Toolbar: Show only the SVG icon when a node also draws a Dashicon Oct 27, 2026

@peterwilsoncc peterwilsoncc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This tests well, I've left a few minor notes inline within the test file.

For testing I used this mini-plugin:

add_action( 'admin_bar_menu', function( $wp_admin_bar ) {
	$wp_admin_bar->add_node(
		array(
			'id'    => 'example1',
			'icon'  => 'core-admin/pin', // Used in 7.2, ignored before.
			'title' => '<span class="ab-icon dashicons-before dashicons-admin-post"></span>' . __( 'Example 1', 'my-plugin' ), // Span replaced by the icon in 7.2.
			'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
		)
	);

	$wp_admin_bar->add_node(
		array(
			'id'    => 'example2',
			'icon'  => 'core-admin/pin', // Used in 7.2, ignored before.
			'title' => __( 'Example 2', 'my-plugin' ),
			'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
		)
	);

	$wp_admin_bar->add_node(
		array(
			'id'    => 'example3',
			// 'icon'  => 'core-admin/pin', // Used in 7.2, ignored before.
			'title' => __( 'Example 3', 'my-plugin' ),
			'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
		)
	);
} );

add_action( 'admin_enqueue_scripts', function() {
	?>
	<style>
		/* Used before 7.2, hidden in 7.2. */
		#wpadminbar #wp-admin-bar-example2 > .ab-item::before,
		#wpadminbar #wp-admin-bar-example3 > .ab-item::before {
			content: "\f109"; /* dashicons-admin-post */
		}
	</style>
	<?php
} );

Comment thread tests/phpunit/tests/adminbar.php Resolved
Comment thread tests/phpunit/tests/adminbar.php Resolved
@fushar

fushar commented Oct 28, 2026

Copy link
Copy Markdown
Author

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

@fushar
fushar requested a review from mcsf October 29, 2026 02:16
@fushar

fushar commented Oct 29, 2026

Copy link
Copy Markdown
Author

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

Comment thread src/wp-includes/class-wp-admin-bar.php Resolved
@sadmansakibnadvi

Copy link
Copy Markdown

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

Copy link
Copy Markdown
Contributor

@propsbot add @mcsf

Comment thread src/wp-includes/class-wp-admin-bar.php Outdated
* @param string $title Node title.
* @return string|false Title without the empty icon element, or false if it has none.
*/
private static function remove_empty_icon_element( $title ) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the HTML API here feels like overkill to me 🤔 How about handling this with CSS only?

When the element is removed on the server under certain conditions, plugin developers can’t tell why it disappeared without reading the core source. With a CSS-only approach, they can find the selector that hides it in the browser dev tools and override it if needed.

In a quick tes, the following CSS gave the same result as this PR, including the unregistered icon case. It would also make the title restoring logic unnecessary, and hide the empty .svg-icon wrapper when the icon is not registered.

#wpadminbar .ab-item:has(> .ab-icon.svg-icon > svg)::before,
#wpadminbar .ab-item:has(> .ab-icon.svg-icon > svg) .ab-icon:not(.svg-icon):empty,
#wpadminbar .ab-icon.svg-icon:empty {
	display: none;
}

One difference is that :empty doesn’t match an icon element with whitespace inside, but I think that’s an acceptable trade-off.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the above CSS work with this scenario: a plugin replaces wp-logo with a title that doesn't have empty span, e.g. <img>...my brand logo</img>

  • Before 7.2: no WP logo (expected)
  • 7.2 trunk: the WP logo SVG icon is not shown. Because we have logic to not show such core node's default icon if the title has no empty span
  • If we replace that logic with your CSS, I think both default WP logo SVG, and the image from the title, are now shown?

@peterwilsoncc

Copy link
Copy Markdown
Contributor

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

Screenshot 2026-10-30 at 1 40 11 pm

@fushar

fushar commented Oct 30, 2026

Copy link
Copy Markdown
Author

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

fushar commented Oct 30, 2026

Copy link
Copy Markdown
Author

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: #14999 (comment)

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

fushar commented Oct 30, 2026 •

Copy link
Copy Markdown
Author

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 also updated the PR description). 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
fushar requested a review from t-hamano October 30, 2026 11:58
Comment thread src/wp-includes/class-wp-admin-bar.php Outdated
Comment on lines +265 to +271
while ( $processor->next_tag( $query ) ) {
$processor->next_token();

if ( 'SPAN' === $processor->get_tag() && $processor->is_tag_closer() ) {
return true;
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scan skips an empty .ab-icon nested directly inside another .ab-icon, so a core node such as wp-logo loses its default icon. Could we keep that inner span as a search candidate and add a nested-span test?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I don't get it. How will this break core's wp-logo, or maybe how can plugin code break that? I think I've listed all possible cases exhaustively here: https://htmlpreview.github.io/?https://github.com/fushar/wordpress-develop/blob/f832b0c4d51b33019381ea23182d0c9a59c061f8/index.html 😄

I also don't think nested .ab-icon spans make sense in admin bar node titles; or at least I've never seen it.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true, core's normal wp-logo title works. Apologies if I wasn't clear.

I meant a plugin-supplied title such as:

  $wp_admin_bar->add_node(
    array(
      'id'    => 'wp-logo',
      'title' => '<span class="ab-icon"><span class="ab-icon"></span></span>Label',
    )
  );

Here, next_token() consumes the inner opening span. The next next_tag() starts after it, so the helper returns false even though the inner span is empty. I reproduced one SVG on the base and none with this PR. I haven't found a plugin using this structure, so I'd treat this as optional robustness and test coverage, not a merge blocker.

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Most of the complexity comes from the wp-logo node. It is there to avoid showing both the WordPress logo and the plugin's own logo when a plugin replaces the title of this node. Another source of complexity is that core nodes mix two ways of getting their icon: some use the icon argument, and others rely on the empty icon element in their title.

As one idea, what do you think about the following approach?

  • All core nodes except wp-logo use the icon argument, and the empty <span class="ab-icon"> is removed from their titles.
  • Only the wp-logo node does not use the icon argument, and the SVG icon is put directly in its title instead. When a plugin replaces the title with its own logo, the SVG icon is replaced along with it.
  • get_default_icon() and the check for an empty icon element in the title are removed.
  • For plugin nodes, keep hiding the old Dashicon (an empty icon element or .ab-item::before) with CSS when there is an SVG icon, as the latest version of this PR does.

This should solve the back-compat issue with wp-logo while keeping the handling of core node icons simpler.

As a trade-off, 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.

I haven't tested it, but the change against trunk would probably look like the following. What do you think? Am I missing anything that would affect backward compatibility?

Diff against trunk
diff --git a/src/wp-includes/admin-bar.php b/src/wp-includes/admin-bar.php
index 1cf33f2..3600b0d 100644
--- a/src/wp-includes/admin-bar.php
+++ b/src/wp-includes/admin-bar.php
@@ -122,10 +122,16 @@ function wp_admin_bar_render() {
  * @access private
  *
  * @param string $icon_name Namespaced icon name, e.g. 'core-admin/wordpress'.
- * @return string Admin bar icon markup. The wrapper is empty if the icon is not found.
+ * @return string Admin bar icon markup, or empty string if the icon is not found.
  */
 function _wp_admin_bar_icon( $icon_name ) {
-	return '<span class="ab-icon svg-icon" aria-hidden="true">' . wp_get_icon( $icon_name ) . '</span>';
+	$icon = wp_get_icon( $icon_name );
+
+	if ( '' === $icon ) {
+		return '';
+	}
+
+	return '<span class="ab-icon svg-icon" aria-hidden="true">' . $icon . '</span>';
 }
 
 /**
@@ -149,7 +155,11 @@ function wp_admin_bar_wp_menu( $wp_admin_bar ) {
 
 	$wp_logo_menu_args = array(
 		'id'    => 'wp-logo',
-		'title' => '<span class="ab-icon" aria-hidden="true"></span><span class="screen-reader-text">' .
+		/*
+		 * Dashicons back-compat: the icon is part of the title, so that a plugin that replaces
+		 * the title with its own logo does not also get the WordPress logo.
+		 */
+		'title' => _wp_admin_bar_icon( 'core-admin/wordpress' ) . '<span class="screen-reader-text">' .
 				/* translators: Hidden accessibility text. */
 				__( 'About WordPress' ) .
 			'</span>',
@@ -255,7 +265,8 @@ function wp_admin_bar_sidebar_toggle( $wp_admin_bar ) {
 		$wp_admin_bar->add_node(
 			array(
 				'id'    => 'menu-toggle',
-				'title' => '<span class="ab-icon" aria-hidden="true"></span><span class="screen-reader-text">' .
+				'icon'  => 'core-admin/menu',
+				'title' => '<span class="screen-reader-text">' .
 						/* translators: Hidden accessibility text. */
 						__( 'Menu' ) .
 					'</span>',
@@ -1016,7 +1027,7 @@ function wp_admin_bar_command_palette_menu( WP_Admin_Bar $wp_admin_bar ): void {
 	$is_apple_os     = (bool) preg_match( "/{$apple_pattern}/i", $_SERVER['HTTP_USER_AGENT'] ?? '' );
 	$shortcut_label  = $is_apple_os ? $shortcut_labels['appleOS'] : $shortcut_labels['default'];
 	$title           = sprintf(
-		'<span class="ab-icon" aria-hidden="true"></span><span class="ab-label"><kbd>%s</kbd><span class="screen-reader-text"> %s</span></span>',
+		'<span class="ab-label"><kbd>%s</kbd><span class="screen-reader-text"> %s</span></span>',
 		$shortcut_label,
 		/* translators: Hidden accessibility text. */
 		__( 'Open command palette' ),
@@ -1049,6 +1060,7 @@ function wp_admin_bar_command_palette_menu( WP_Admin_Bar $wp_admin_bar ): void {
 	$wp_admin_bar->add_node(
 		array(
 			'id'    => 'command-palette',
+			'icon'  => 'core-admin/search',
 			'title' => $title,
 			'href'  => '#',
 			'meta'  => array(
@@ -1113,11 +1125,12 @@ function wp_admin_bar_new_content_menu( $wp_admin_bar ) {
 		return;
 	}
 
-	$title = '<span class="ab-icon" aria-hidden="true"></span><span class="ab-label">' . _x( 'New', 'admin bar menu group label' ) . '</span>';
+	$title = '<span class="ab-label">' . _x( 'New', 'admin bar menu group label' ) . '</span>';
 
 	$wp_admin_bar->add_node(
 		array(
 			'id'    => 'new-content',
+			'icon'  => 'core-admin/plus',
 			'title' => $title,
 			'href'  => admin_url( array_key_first( $actions ) ),
 			'meta'  => array(
@@ -1171,14 +1184,14 @@ function wp_admin_bar_comments_menu( $wp_admin_bar ) {
 		number_format_i18n( $awaiting_mod )
 	);
 
-	$icon   = '<span class="ab-icon" aria-hidden="true"></span>';
 	$title  = '<span class="ab-label awaiting-mod pending-count count-' . $awaiting_mod . '" aria-hidden="true">' . number_format_i18n( $awaiting_mod ) . '</span>';
 	$title .= '<span class="screen-reader-text comments-in-moderation-text">' . $awaiting_text . '</span>';
 
 	$wp_admin_bar->add_node(
 		array(
 			'id'    => 'comments',
-			'title' => $icon . $title,
+			'icon'  => 'core-admin/comment',
+			'title' => $title,
 			'href'  => admin_url( 'edit-comments.php' ),
 		)
 	);
@@ -1286,14 +1299,14 @@ function wp_admin_bar_updates_menu( $wp_admin_bar ) {
 		number_format_i18n( $update_data['counts']['total'] )
 	);
 
-	$icon   = '<span class="ab-icon" aria-hidden="true"></span>';
 	$title  = '<span class="ab-label" aria-hidden="true">' . number_format_i18n( $update_data['counts']['total'] ) . '</span>';
 	$title .= '<span class="screen-reader-text updates-available-text">' . $updates_text . '</span>';
 
 	$wp_admin_bar->add_node(
 		array(
 			'id'    => 'updates',
-			'title' => $icon . $title,
+			'icon'  => 'core-admin/update',
+			'title' => $title,
 			'href'  => network_admin_url( 'update-core.php' ),
 		)
 	);
diff --git a/src/wp-includes/class-wp-admin-bar.php b/src/wp-includes/class-wp-admin-bar.php
index a657ec7..6c8bbef 100644
--- a/src/wp-includes/class-wp-admin-bar.php
+++ b/src/wp-includes/class-wp-admin-bar.php
@@ -117,7 +117,9 @@ class WP_Admin_Bar {
 	 *     @type string $id     ID of the item.
 	 *     @type string $title  Title of the node.
 	 *     @type string $icon   Optional. Namespaced icon name in the form "collection/icon-name",
-	 *                          e.g. 'core-admin/pin'. Rendered before the title.
+	 *                          e.g. 'core-admin/pin'. Rendered before the title, and hides a
+	 *                          Dashicon that the node draws in an empty `<span class="ab-icon">`
+	 *                          or on `.ab-item::before`. Ignored if the icon is not registered.
 	 *     @type string $parent Optional. ID of the parent node.
 	 *     @type string $href   Optional. Link for the item.
 	 *     @type bool   $group  Optional. Whether or not the node is a group. Default false.
@@ -183,68 +185,6 @@ class WP_Admin_Bar {
 		$this->_set_node( $args );
 	}
 
-	/**
-	 * Dashicons back-compat: returns the default icon for a node ID that core registers.
-	 *
-	 * The icons of these nodes used to be added with CSS rules for the node ID,
-	 * in one of two ways. A node that has no icon of its own gets the icon under
-	 * the same condition as before:
-	 *
-	 * - On `.ab-item::before`: the node gets the icon whatever its title is. The
-	 *   `my-account` node only gets it without the `with-avatar` class.
-	 * - On `.ab-icon::before`: the node gets the icon in place of the empty
-	 *   `<span class="ab-icon">` of its title, and no icon without that element.
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param object $node The node.
-	 * @return array|false {
-	 *     Default icon, or false if the node has none.
-	 *
-	 *     @type string $icon     Namespaced icon name.
-	 *     @type bool   $in_title Whether the icon takes the place of the empty icon element of the title.
-	 * }
-	 */
-	private static function get_default_icon( $node ) {
-		$id            = $node->id;
-		$default_icons = array(
-			// On `.ab-item::before`.
-			'site-name'       => array( 'core-admin/dashboard', false ),
-			'my-sites'        => array( 'core-admin/sites', false ),
-			'site-editor'     => array( 'core-admin/brush', false ),
-			'customize'       => array( 'core-admin/brush', false ),
-			'edit'            => array( 'core-admin/pencil', false ),
-			'my-account'      => array( 'core-admin/people', false ),
-			// On `.ab-icon::before`, in the title.
-			'wp-logo'         => array( 'core-admin/wordpress', true ),
-			'menu-toggle'     => array( 'core-admin/menu', true ),
-			'command-palette' => array( 'core-admin/search', true ),
-			'new-content'     => array( 'core-admin/plus', true ),
-			'comments'        => array( 'core-admin/comment', true ),
-			'updates'         => array( 'core-admin/update', true ),
-		);
-
-		if ( ! isset( $default_icons[ $id ] ) ) {
-			return false;
-		}
-
-		// The account icon is only for a node without an avatar.
-		if ( 'my-account' === $id && in_array( 'with-avatar', explode( ' ', $node->meta['class'] ?? '' ), true ) ) {
-			return false;
-		}
-
-		$icon = $default_icons[ $id ][0];
-
-		if ( 'site-name' === $id && ( is_admin() || ! current_user_can( 'read' ) ) ) {
-			$icon = 'core-admin/home';
-		}
-
-		return array(
-			'icon'     => $icon,
-			'in_title' => $default_icons[ $id ][1],
-		);
-	}
-
 	/**
 	 * @since 3.3.0
 	 *
@@ -641,24 +581,8 @@ class WP_Admin_Bar {
 			$menuclass = ' class="' . esc_attr( trim( $menuclass ) ) . '"';
 		}
 
-		$title     = $node->title;
 		$icon_name = $node->icon;
 
-		// Dashicons back-compat: a core node that was given no icon gets its default icon.
-		$default_icon = self::get_default_icon( $node );
-
-		// Dashicons back-compat: the icon replaces the first empty `<span class="ab-icon">` in the title; without one, the node gets no default icon.
-		if ( $default_icon && $default_icon['in_title'] ) {
-			$title = preg_replace( '/<span\b[^>]*\bclass=(["\'])(?:[^"\']*\s)?ab-icon(?:\s[^"\']*)?\1[^>]*>\s*<\/span>/', '', (string) $title, 1, $count );
-			if ( ! $count ) {
-				$default_icon = false;
-			}
-		}
-
-		if ( ! $icon_name && $default_icon ) {
-			$icon_name = $default_icon['icon'];
-		}
-
 		$icon = '';
 		if ( wp_is_valid_icon_name( $icon_name ) ) {
 			$icon = _wp_admin_bar_icon( $icon_name );
@@ -699,7 +623,7 @@ class WP_Admin_Bar {
 			}
 		}
 
-		echo ">{$arrow}{$icon}{$title}";
+		echo ">{$arrow}{$icon}{$node->title}";
 
 		if ( $has_link ) {
 			echo '</a>';
diff --git a/src/wp-includes/css/admin-bar.css b/src/wp-includes/css/admin-bar.css
index eab5e89..d95093e 100644
--- a/src/wp-includes/css/admin-bar.css
+++ b/src/wp-includes/css/admin-bar.css
@@ -278,6 +278,17 @@ html:lang(he-il) .rtl #wpadminbar * {
 	text-indent: 0;
 }
 
+/*
+ * Dashicons back-compat: hide a Dashicon next to the SVG icon, except `.ab-icon::before` on core nodes,
+ * and the icon in the title of the `wp-logo` node when the node is given an icon.
+ */
+#wpadminbar .ab-item:has(> .ab-icon.svg-icon)::before,
+#wpadminbar .ab-item:has(> .ab-icon.svg-icon) .ab-icon:not(.svg-icon):empty,
+#wpadminbar li:not(#wp-admin-bar-site-name, #wp-admin-bar-my-sites, #wp-admin-bar-site-editor, #wp-admin-bar-customize, #wp-admin-bar-edit, #wp-admin-bar-my-account, #wp-admin-bar-wp-logo, #wp-admin-bar-menu-toggle, #wp-admin-bar-command-palette, #wp-admin-bar-new-content, #wp-admin-bar-comments, #wp-admin-bar-updates) > .ab-item > .ab-icon.svg-icon::before,
+#wpadminbar .ab-item > .ab-icon.svg-icon ~ .ab-icon.svg-icon {
+	display: none;
+}
+
 #wpadminbar .ab-icon.svg-icon svg {
 	flex: none;
 	width: 24px;

@fushar

fushar commented Nov 2, 2026

Copy link
Copy Markdown
Author

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.

@t-hamano

t-hamano commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

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

fushar commented Nov 2, 2026

Copy link
Copy Markdown
Author

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

@t-hamano

t-hamano commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

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

fushar commented Nov 2, 2026

Copy link
Copy Markdown
Author

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:

image

Everything else is good.

@t-hamano

t-hamano commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Thanks for the comparison, @fushar!


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

image

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.

image

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

fushar commented Nov 3, 2026

Copy link
Copy Markdown
Author

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.

@t-hamano

t-hamano commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

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

Personally, I prefer this one 👍

@t-hamano

t-hamano commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

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

Mamaduka commented Nov 3, 2026

Copy link
Copy Markdown
Member

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

…-ab-item-before-with-svg-icon

# Conflicts:
#	tests/phpunit/tests/adminbar.php

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At this point, this seems to be the best approach. Unless anyone has any objections, I plan to commit this in time for today's Beta 4 release.

wporg-sync pushed a commit that referenced this pull request Nov 3, 2026
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 #14999

Follow-up to [64583].

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

git-svn-id: https://develop.svn.wordpress.org/trunk@65223 602fd350-edb4-49c9-b593-d223f7449a82
wporg-sync pushed a commit to WordPress/WordPress that referenced this pull request Nov 3, 2026
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 WordPress/wordpress-develop#14999

Follow-up to [64583].

Props fushar, mamaduka, mciampini, mcsf, peterwilsoncc, sadmansakibnadvi, wildworks.
See #65089.
Built from https://develop.svn.wordpress.org/trunk@65223


git-svn-id: http://core.svn.wordpress.org/trunk@64372 1a063a9b-81f0-0310-95a4-ce76da25c4cd

@mcsf mcsf left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trusting the reviews/judgement of the other committers in this PR, but this looks good from a superficial glance! I'm happy to see simplifications in the PHP logic, so thanks. :)
I think a comment could be polished, but that's a minor thing.

Comment on lines +289 to +290
* Dashicons back-compat: hide a Dashicon next to the SVG icon, except `.ab-icon::before` on core nodes,
* and the icon in the title of the `wp-logo` node when the node is given an icon.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can improve this comment, because I think future readers will have a hard time understanding this without spending some time reading this very PR:

  • what does "hide Dashicon next to the SVG icon" mean? -> explain that, for compat, we render both these things, and the new one is X, and we hide the element of Y, etc.
  • why is wp-logo special? -> explain something along the lines of: we don't want to break plugins that replace the WP logo, so we kept its rendering in the old style

@peterwilsoncc

Copy link
Copy Markdown
Contributor

Merged r65223 / 855f071

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants