Customizing (or Removing) the WordPress Admin Toolbar

Customizing (or Removing) the WordPress Admin Toolbar

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

default toolbar
WordPress Toolbar

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

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

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

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

Site name menu
Site name menu

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

The default menu at the top compared to the customized <em>My Account</em> menu in the toolbar
The default menu at the top compared to the customized My Account menu in the toolbar

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.

The Pending Posts menu will be available only to site editors
The Pending Posts menu will be available only to site editors

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.

Wrapping Up

Left as is, the toolbar might seem like a necessary and unsightly blight at the top of your website. But when you consider its possible uses and the potential for customization, it quickly becomes apparent 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 websites? 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.
Aileen Javier
Aileen Javier A past writer for WPMU DEV