The WordPress toolbar is that thin black bar that sits above the page header of your website. It contains menus and links usually pointing to specific admin pages like the editing post pages, the user profile page, the Theme Customizer, and more.
While the toolbar has many useful features, it can be annoying, particularly when you have no need to grant access to the backend of your site to all your users, or when you don’t necessarily consider a black rectangle aesthetically acceptable for your website.
But the toolbar is an important part of the WordPress admin and can be extremely useful with the right customizations so you can provide your collaborators with a quick access to site functionalities and specific information.
That being said, in this article I will show you how to manage the WordPress toolbar, removing it for specific roles, adding links and menus, and customizing its appearance.
Removing the Admin Toolbar
Occasionally, you might want to remove the toolbar from the front-end of your site. You can hide it to all users or for specific roles. The following line – when added to your functions.php file (don’t forget to use a child theme!) – will remove the toolbar for all site users:
The WordPressCodex states that the
show_admin_bar function should be called immediately upon plugin load and does not need to be called from a function hooked to the
More probably, you may want to show/hide the toolbar depending on a user’s capabilities or role name. The following code will hide the admin bar to all users but administrators and editors:
I said before that the
show_admin_bar function does not need to be called from a callback function. So, you may ask why we’re hooking it to the
after_setup_theme action? In this case, if we didn’t, WordPress would return the following error message:
Fatal error: Call to undefined function wp_get_current_user() …
That’s because the
current_user_can() function uses
wp_get_current_user() to retrieve the current user object. This latter function is not available when the plugin loads, so we have to be sure to call
current_user_can not before the
plugins_loaded action (check the Codex for a list of typical actions in chronological order). If you’re calling
current_user_can() from within a theme’s (or child theme’s) function file, you’ll need to hook the callback function to the
after_setup_theme action, instead.
In this second example, we’re removing the toolBar for all users except administrators and editors:
If you want your code to be reusable, it would be preferable to hook the function to the
after_setup_theme action in any case.
Since version 3.1, WordPress has provided the
show_admin_bar filter, so we have another way to accomplish the same task. For example, we can hide the toolbar to all users with a single statement:
That’s the same as the following lines:
And we can show/hide the toolbar depending on a user’s capabilities, as well:
In this example, the toolbar will be shown only to administrators and editors (they can
That’s all that we have to know when we decide to remove the toolbar. But what if we wanted to use the Toolbar to give new powers to our WordPress install?
Customizing the Admin Toolbar
WP_Admin_Bar Class controls the toolbar. Thanks to the class methods we can add and remove menu elements (nodes) and groups of elements.
In our examples we’re going to use just the following three methods:
Default menus are defined in /wp-includes/admin-bar.php. Some of them are available for all logged-in users, like the WordPress Logo menu (which shows some institutional links), the My Account menu (which shows some links related to the current user), and Site Name menu (which provides quick links to the admin panel).
But WordPress gives us the ability to add custom menus and links, textual information and form fields. I won’t explain here how to add items to the toolbar, as we’ve already covered this topic in How to Add Items to the WordPress Toolbar. Rather, I will show you two practical examples of customization, starting with an easy upgrade of the built-in My Account menu.
How to add new items to an existing menu
When our goal is adding nodes to the toolbar depending on the user’s role, we have to define a callback function keeping as argument an instance of the
WP_Admin_Bar object. The function should be hooked to the
admin_bar_menu action as shown in the following code:
I mentioned earlier in this article that we can build new menus as well as adding links to existing menus. In this example, we’re going to provide the current user with a quick link to his/her personal website, adding a new node to the My Account built-in menu.
When the admin-bar.php loads, a new group of nodes named
user-actions is added to the
my-account menu. This group of nodes will be considered parent for any new custom link we adding to the menu. The following code will add the link to the group:
First, we get the
$current_user object and check if it is a valid instance of
WP_User. Then we get the
my-account node object, which corresponds to the My Account menu placed on the right side of the Toolbar. Finally, if the
user_url meta field and the node object exist, then we add the
user-url node to the menu.
The code above will generate the following mark-up:
The resulting menu is shown in the image below.
An Advanced Example: Conditional Menus, Custom Post Types and More
Some Toolbar menus are available only in specific pages. For instance, the Edit post menu, which provides a quick link to the editing page of the current post or taxonomy term, appears exclusively in single post pages and taxonomy archives.
This may suggest to us the idea of showing up menus under specific conditions. In the following example, the condition will be provided by the user role.
So, we may like to show to the site editors a role-specific menu holding a group of links pointing to the admin screens of pending posts (one link for each post type). This sort of menu would be extremely useful for multi-author websites, when many users write posts (and custom post types) expecting to be reviewed for publication.
Now, let’s get back to our callback function and add the following code:
In the code above, first we check whether the current user is an editor. If he/she is, we add the
editor-menu top level node (no parent for this node). Later, we add the
editor-actions group, setting the
editor-menu item as its parent node.
Now comes the funny part. The
get_post_types function retrieves from the database an array of custom post type objects (more in the Codex). For each post type, we check if the logged-in user has the role of editor (she can
publish_posts). Then we get an array of all pending posts in the current post type and count them.
Finally, for each post type we add a node to the
editor-actions group. Each link will point to the pending post type screen.
And, if you’d like to customize the menu presentation with a gorgeous icon from Dashicon set, just append the following code to your plugin or functions.php file:
The function we’ve hooked to the
wp_head action just prints a style element within the
head of the document. Sure, this is not a best practice when you enqueue a style in a document, but here I assume that we just need one style declaration. Loading a whole CSS file would not be an efficient option.
But if you want to merge the toolbar into the look and feel of your website, you will have to overwrite the styles declared in /wp-includes/css/admin-bar.css, and enqueue your stylesheets the right way, as well explained in Adding Scripts and Styles to WordPress the Right Way With Enqueueing.
Left as as is, the toolbar might seem like an necessary and unsightly blight at the top of your website. But when you consider its possible uses, and the potentional for customization, it quickly becomes apparents how much of a useful and flexible tool the toolbar can be, both for site owners and all users who collaborate on a website.
Are you using the toolbar on your webisites? Have you ever added new menus or advanced functionalities? Have you got any ideas you’d like to implement but you still haven’t? Share them with us in the comments below.