The Admin Bar (also called Toolbar) API provides a way to add, modify, and remove items from the WordPress admin bar that appears at the top of both front-end and admin pages for logged-in users.

Architecture

Core Components

Global Instance

global $wp_admin_bar;

The admin bar is instantiated as a global $wp_admin_bar object during the wp_loaded action via _wp_admin_bar_init().

Node System

The admin bar is built as a tree of nodes. Each node can be:

• Item – A clickable menu item (default)
• Group – An organizational container for items
• Container – Auto-generated wrapper for nested groups

Node Structure

$node = array(
    'id'     => 'my-item',           // Required: unique identifier
    'title'  => 'My Item',           // Display text/HTML
    'parent' => 'parent-id',         // Parent node ID (default: 'root')
    'href'   => 'https://example.com', // Link URL
    'group'  => false,               // true = group, false = item
    'meta'   => array(               // Additional attributes
        'class'      => 'my-class',
        'html'       => '<span>Extra HTML</span>',
        'onclick'    => 'javascript:void(0)',
        'target'     => '_blank',
        'title'      => 'Tooltip text',
        'rel'        => 'noopener',
        'lang'       => 'en',
        'dir'        => 'ltr',
        'tabindex'   => 0,
        'menu_title' => 'ARIA menu name',
    ),
);

Node Hierarchy

root
├── wp-logo (WordPress logo menu)
│   ├── about
│   ├── contribute
│   └── wp-logo-external (group)
│       ├── wporg
│       ├── documentation
│       └── support-forums
├── site-name (Site menu)
│   ├── dashboard / view-site
│   └── appearance (group)
├── my-sites (Multisite only)
├── customize / site-editor
├── updates
├── comments
├── new-content ("+ New" menu)
├── edit
└── top-secondary (group, right-aligned)
    ├── my-account
    ├── recovery-mode
    └── search

Rendering Flow

1. Initialization (_wp_admin_bar_init())

   • Check is_admin_bar_showing()
   • Instantiate WP_Admin_Bar class
   • Call initialize() and add_menus()

2. Menu Population (admin_bar_menu action)

   • Core menus added via add_menus()
   • Plugins/themes add custom nodes

3. Binding (_bind())

   • Build node tree from flat array
   • Wrap orphan items in groups
   • Handle nested groups with containers

4. Rendering (render())

   • Fire wp_before_admin_bar_render
   • Output HTML via _render(), _render_group(), _render_item()
   • Fire wp_after_admin_bar_render

Visibility Control

Show/Hide Functions

// Hide admin bar globally
show_admin_bar( false );

// Check if showing
if ( is_admin_bar_showing() ) {
    // Admin bar is visible
}

Automatic Hiding

The admin bar is automatically hidden for:

• XMLRPC requests
• AJAX requests
• iFrame requests
• JSON requests
• Embedded content
• Logged-out users (front-end)
• wp-login.php page

Default Menu Priorities

CSS Classes

Container Classes

Item Classes

State Classes

User Preferences

Users can control admin bar visibility via their profile settings:

// Get user preference (front-end)
$show = _get_admin_bar_pref( 'front', $user_id );

// Stored as user meta
// show_admin_bar_front = 'true' | 'false'

Theme Support

Themes can customize the admin bar bump (spacing):

// Use default bump callback
add_theme_support( 'admin-bar' );

// Use custom callback
add_theme_support( 'admin-bar', array(
    'callback' => 'my_admin_bar_bump',
) );

// Disable bump entirely
add_theme_support( 'admin-bar', array(
    'callback' => '__return_false',
) );

Default bump CSS:

@media screen { html { margin-top: 32px !important; } }
@media screen and (max-width: 782px) { html { margin-top: 46px !important; } }

Multisite Considerations

On multisite installations:

• wp_admin_bar_my_sites_menu() shows all user blogs
• Site icons can be shown (filterable via wp_admin_bar_show_site_icons)
• Network Admin links appear for super admins
• Blog switching uses switch_to_blog() / restore_current_blog()