How to Customize the WordPress 3.3 Toolbar

Contributing Editor

You can make the WordPress interface easier for clients by removing unnecessary menus, widgets and meta boxes. However, in WordPress 3.3, the admin and header bars have been merged to create a single toolbar. It may also contain options you want to hide…

The WordPress Toolbar API

The new toolbar is defined using a single WP_Admin_Bar object (see wp-includes/class-wp-admin-bar.php). This provides a number of useful methods:

  • add_node() — add a new toolbar item
  • remove_node() — remove a toolbar item
  • get_node() — fetch a node’s properties
  • get_nodes() — fetch a list of all nodes

Removing Toolbar Items

We’re going to place our code into a reusable plugin named wp-content/plugins/change-toolbar.php but you could put it within your theme’s functions.php file.

WordPress plugins require a header at the top of the file, e.g.


<?php
/*
Plugin Name: Change Toolbar
Plugin URI: http://www.sitepoint.com/change-wordpress-33-toolbar
Description: Modifies the WordPress 3.3+ toolbar.
Version: 1.0
Author: Craig Buckler
Author URI: http://optimalworks.net/
License: GPL2
*/

We now require a single function where our changes will be made:


function change_toolbar($wp_toolbar) {
	/* ... code to go here ... */
}

followed by an action hook which runs the function and passes the toolbar object:


add_action('admin_bar_menu', 'change_toolbar', 999);

We can now remove toolbar items within the change_toolbar() function. For example, the following line hides the WordPress logo and help sub-menu by referencing its ID, “wp-logo”:


$wp_toolbar->remove_node('wp-logo');

To remove other items you need to discover what ID they’re using. You could delve into the PHP code but there’s an easier way:

  • Open Firebug or your favorite Firebug-like development console.
  • Locate the toolbar item you want to remove (in most browsers you can right-click the item and select “Inspect Element”).
  • Navigate up the parent nodes until you find an LI tag. It will have an ID starting “wp-admin-bar-” followed by the internal ID code:

WordPress toolbar ID

In this example, the Comments item is highlighted. Therefore, to remove it from the toolbar, we use:


$wp_toolbar->remove_node('comments');

Adding Toolbar Items

We can add toolbar items within the same function. The syntax is:


$wp_toolbar->add_node($arg);

Where $arg is an associative array containing:

  • id — the item’s ID
  • title — the title text
  • parent — the parent menu ID (optional)
  • href — the link URL (optional)
  • group — true if the node is a group (optional)
  • meta — another array providing other keys including: html, class, onclick, target, title, tabindex

Let’s add a “Help” item which links to our support pages:


$wp_toolbar->add_node(array(
	'id' => 'myhelp',
	'title' => 'Help',
	'href' => 'http://mysite.com/support/',
	'meta' => array('target' => 'help')
));

We could now add an email support link within a sub-menu by referencing the ‘myhelp’ ID in the parent:


$wp_toolbar->add_node(array(
	'id' => 'mysupport',
	'title' => 'Email Support',
	'parent' => 'myhelp',
	'href' => 'mailto:support@mysite.com?subject=support%20request'
));

I hope you find it useful — it’s easy to customize the whole WordPress 3.3 toolbar using a few API calls.

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Eric

    There are definitely some subtleties to watch out for with the new API. You should pass a $wp_toolbar variable to the action hook, instead of accessing a global. Also, be sure to explicitly set a priority for add_action() when removing any of WP’s default nodes, because they don’t exist yet at the default priority (10).

  • http://www.byobwebsite.com Rick Anderson

    This was really a terrific article! I was able to figure out how to remove the default WordPress search and replace it with my Google custom site search. The trick here was learning that first I needed to create a node and then create a menu for that node.

    If anyone else is trying to figure this out, here’s what I did.

    function byob_customize_toolbar($wp_toolbar){
    $wp_toolbar->remove_node('search');

    $wp_toolbar->add_node( array(
    'id' => 'byob-secondary',
    'title' => 'Search BYOBWebsite'
    ) );

    $form = '';
    $form .= '';
    $form .= '';
    $form .= '';
    $form .= '';
    $form .= '';
    $form .= '';
    $form .= '';

    $wp_toolbar->add_menu(array(
    'id' => 'byob-search',
    'parent' => 'byob-secondary',
    'title' => $form,
    'meta' => array(
    'class' => 'byob-admin-bar-search',
    'tabindex' => -1,
    )
    ));

    }
    add_action('admin_bar_menu', 'byob_customize_toolbar', 999);

    I’d have never gotten here without your help.

  • http://www.fethiyedays.com tuna

    thanx for the information, i was trying to solve this

  • http://www.kreativtheme.com Kreativ Theme

    Thanks, this info is great for creating notifications on the toolbar, spcially useful for plugin … thanks!