How to Add a Custom Menu to the WordPress Admin Bar

Screenshot of the WordPress Admin Bar with Several Menu Items
The WordPress Admin Bar

The WordPress admin bar can be a useful place to have shortcuts to the various sections or actions of your WordPress plugin. In this tutorial, I’ll show you how to add your own admin bar menu item and show you some various use cases for creating your own menu item. For completeness, I’ll also show you some cool tricks you can do with the admin bar.

Should you add a custom admin bar menu to your plugin?

Providing users with an easy-to-use interface and positive user experience is critical for any plugin developer. The admin bar is a prominent location in the WordPress admin, allowing quick access to a variety of options. For example, you can create new posts directly from the admin bar.

Adding a New Post is Easy Using the Admin Bar
Adding a New Post is Easy Using the Admin Bar

If your plugin has settings that are commonly used, perhaps you should consider adding a custom menu to the admin bar. You can save users some steps or from having to dig through various admin setting options.

Query Monitor Admin Bar Items
Query Monitor Uses the Admin Bar for Debugging Shortcuts

Admin bar pros

Here are some pros for creating an admin bar item.

  • Accessibility and discovery: a custom menu in the admin bar can provide quick and easy access to frequently used features of your plugin.
  • Branding: a custom menu is great for branding and providing extra visibility to your installed plugin.
  • Customization: you can choose which of your plugin’s features and shortcuts to highlight and can tailor the menu dynamically based on a user’s settings.

Admin bar cons

There are some drawbacks to adding a menu to the admin bar.

  • Clutter: the admin bar is only so large, and depending on the plugins installed, the admin bar could be a mess if many plugins add their own menus.
  • Confusion: not all admin bar menus make their purpose clear and might actually confuse users further on how to use your plugin.
  • Fallout: you will have some unhappy users who simply hate the idea of your plugin adding an admin bar menu.

Or, as one Twitter user so eloquently put it:

When adding a custom menu, you’ll need to keep the end user’s needs in mind. After all, it is their dashboard that is being affected when choosing to add the menu.

While the opinion of whether or not to add something to the admin bar is subjective and depends on the scenario, try to make the admin bar useful for the end user.

EDD's Admin Bar and its Shortcuts
EDD’s Admin Bar Item Isn’t All That Useful

Ultimately, the decision to add an admin bar item is up to you.

How to add a a top-level menu to the admin bar

Let’s start with the basics. We’ll need to add an action for admin_bar_menu. Here’s how it would look.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Run admin bar code here.
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );Code language: PHP (php)

From there, we can call methods on the $admin_bar object in order to add the items.

Let’s begin by creating a top-level admin bar item.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Run admin bar code here. Will run on both frontend and backend.
	$admin_bar->add_menu(
		array(
			'id'    => 'my-plugin-menu',
			'title' => 'My Plugin',
			'href'  => false,
			'meta'  => array(
				'class' => 'my-plugin-class',
				'title' => 'My Plugin Menu',
			),
		)
	);
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );
Code language: PHP (php)
Custom Admin Bar Menu Item
Custom Admin Bar Menu Item

In this example, I’m calling method add_menu, which will add a top-level admin bar item. Let’s break down what each parameters mean and list some additional ones that are available.

id (string)

'id' => 'my-plugin-menu',Code language: PHP (php)

The id argument is essentially a slug for your menu item. It should be unique, and something other people can reference.

title (string)

'title' => 'My Plugin',Code language: PHP (php)

The title argument is used for setting the label in the admin bar for the menu item.

href (string or boolean) (optional)

'href' => false,Code language: PHP (php)

Provide false to have a text-only menu item or set a URL the user should go to when the menu item is clicked.

parent (string) (optional)

You’re able to add menus under existing items, which is where the parent argument comes into play. You’d pass it the parent node’s id attribute value.

group (boolean) (optional)

Whether or not a node is a group. Group nodes aren’t visible unless there are children added to the node.

meta (array) (optional)

An optional array with some meta enhancements you can add like hover title, CSS classes, and even custom HTML.

Here are the array arguments you can use:

  • html – The html used for the node.
  • class – The class attribute for the list item containing the link or text node.
  • rel – The rel attribute.
  • onclick – The onclick attribute for the link. This will only be set if the href argument is present.
  • target – The target attribute for the link. This will only be set if the href argument is present.
  • title – The title attribute. Will be set to the link or to a div containing a text node.
  • tabindex – The tabindex attribute. Will be set to the link or to a div containing a text node.

Adding an icon to the top-level admin bar item

Let’s use the previous example, but instead let’s add an SVG icon next to our title.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Run admin bar code here. Will run on both frontend and backend.

	$svg_code = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="16" height="16" style="vertical-align: middle; margin-right: 5px;"><path fill="#FFFFFF" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>';
	$admin_bar->add_menu(
		array(
			'id'    => 'my-plugin-menu',
			'title' => $svg_code . 'My Plugin',
			'href'  => 'https://domain.com/wp-admin/admin.php?page=my-plugin',
			'meta'  => array(
				'class' => 'my-plugin-class',
				'title' => 'My Plugin Menu',
			),
		)
	);
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );
Code language: PHP (php)

In the above example, I’ve used an SVG from FontAwesome to demonstrate that you can use an SVG as an icon and have it show up next to your menu item.

Icon Next to Admin Bar Menu Item
Icon Next to Admin Bar Menu Item

You can also use images in place of the SVG by just including the HTML in the title argument.

Adding child nodes to an admin bar menu item

Let’s modify our example to add a child menu item. We’ll be using add_node for the child item, which behaves exactly the same as add_menu.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Run admin bar code here. Will run on both frontend and backend.

	$svg_code = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="16" height="16" style="vertical-align: middle; margin-right: 5px;"><path fill="#FFFFFF" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>';

	// Add a new top level menu item.
	$admin_bar->add_menu(
		array(
			'id'    => 'my-plugin-menu',
			'title' => $svg_code . 'My Plugin',
			'href'  => 'https://domain.com/wp-admin/admin.php?page=my-plugin',
			'meta'  => array(
				'class' => 'my-plugin-class',
				'title' => 'My Plugin Menu',
			),
		)
	);

	// Add a submenu to the above item. add_menu is just a wrapper for add_node.
	$admin_bar->add_node(
		array(
			'parent' => 'my-plugin-menu',
			'id'     => 'my-plugin-submenu-1',
			'title'  => 'Submenu 1',
			'href'   => 'https://domain.com/wp-admin/admin.php?page=my-plugin&tab=settings',
			'meta'   => array(
				'class' => 'my-plugin-submenu-1-class',
				'title' => 'Submenu 1',
			),
		)
	);
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );
Code language: PHP (php)

In the example above, I’m setting the parent of the node to my-plugin-menu, which is the ID of the parent.

Child Menu Item in the Admin Bar
Child Menu Item in the Admin Bar

You can go even further by adding a child node to the child onde.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Run admin bar code here. Will run on both frontend and backend.

	$svg_code = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="16" height="16" style="vertical-align: middle; margin-right: 5px;"><path fill="#FFFFFF" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>';

	// Add a new top level menu item.
	$admin_bar->add_menu(
		array(
			'id'    => 'my-plugin-menu',
			'title' => $svg_code . 'My Plugin',
			'href'  => 'https://domain.com/wp-admin/admin.php?page=my-plugin',
			'meta'  => array(
				'class' => 'my-plugin-class',
				'title' => 'My Plugin Menu',
			),
		)
	);

	// Add a submenu to the above item.
	$admin_bar->add_node(
		array(
			'parent' => 'my-plugin-menu',
			'id'     => 'my-plugin-submenu-1',
			'title'  => 'Submenu 1',
			'href'   => 'https://domain.com/wp-admin/admin.php?page=my-plugin&tab=settings',
			'meta'   => array(
				'class' => 'my-plugin-submenu-1-class',
				'title' => 'Submenu 1',
			),
		)
	);

	// Add a child node to the above submenu item.
	$admin_bar->add_node(
		array(
			'parent' => 'my-plugin-submenu-1',
			'id'     => 'my-plugin-submenu-1-child',
			'title'  => 'Submenu 1 Child',
			'href'   => 'https://domain.com/wp-admin/admin.php?page=my-plugin&tab=settings',
			'meta'   => array(
				'class' => 'my-plugin-submenu-1-child-class',
				'title' => 'Submenu 1 Child',
			),
		)
	);
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );
Code language: HTML, XML (xml)
Child Node of a Child Node
Child Node of a Child Node

Note the use of the parent argument. By setting this argument, you can allow nesting of the menu items.

Adding nodes to existing admin bar items

Let’s pivot and demonstrate how to add a node to an existing menu item, rather than creating your own.

First, you need to know the ID of the admin bar item. I recommend opening up your Inspect Element browser tools, and using the ID that is present in the HTML LI element.

Admin Bar HTML and Attributes
Admin Bar HTML and Attributes

In each LI element, there are IDs, prefixed with wp-admin-bar-. In the above screenshot, you can see there is:

  • wp-logo
  • site-name
  • customize
  • updates
  • comments
  • new-content
  • query-monitor

Let’s go ahead and add a link to the Site Health admin screen underneath the updates admin bar item.

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Only show to admins.
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	// Add site health to admin bar under updates.
	$admin_bar->add_node(
		array(
			'parent' => 'updates',
			'id'     => 'my-plugin-site-health',
			'title'  => 'Site Health',
			'href'   => esc_url( admin_url( 'site-health.php' ) ),
			'meta'   => array(
				'class' => 'my-plugin-site-health',
				'title' => 'Site Health',
			),
		)
	);
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 50 );
Code language: PHP (php)
Site Health Shortcut Under Updates Menu Item
Site Health Shortcut Under Updates Menu Item

In this particular case, I’m using updates as the parent and then creating the shortcut.

Removing admin bar menu items

In this example, let’s remove the comments, updates, and the WordPress logo from the admin bar. First, I need to get the IDs for each item.

After scanning the HTML elements, the IDs end up being:

  • wp-logo
  • comments
  • updates

Here’s the resulting code:

<?php

/**
 * Add a new admin bar menu item.
 *
 * @param WP_Admin_Bar $admin_bar Admin bar reference.
 */
function my_plugin_add_admin_bar_items( $admin_bar ) {
	// Only show to admins.
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	$nodes_to_remove = array(
		'wp-logo',
		'comments',
		'updates',
	);
	foreach ( $nodes_to_remove as $node_id ) {
		$admin_bar->remove_node( $node_id );
	}
}
add_action( 'admin_bar_menu', 'my_plugin_add_admin_bar_items', 100 );Code language: PHP (php)

This time I’m using method remove_node to remove the menu items.

Here’s the end result after removing the nodes.

Mostly Clutter Free Admin Bar
Mostly Clutter Free Admin Bar

Conclusion

In this tutorial, I explained the pros and cons of admin an admin bar menu. I showed how to add a top level item, adding an item to an existing parent, and how to remove menu bar items.

If you have any questions, please leave a comment below and I’ll be sure to respond.

Ronald Huereca
By: Ronald Huereca
Published On: on May 10, 2023

Ronald Huereca founded DLX Plugins in 2022 with the goal of providing deluxe plugins available for download. Find out more about DLX Plugins, check out some tutorials, and check out our plugins.

Shopping Cart
  • Your cart is empty.
Scroll to Top