banner

How to add a custom link to the WordPress admin/toolbar with icon

In this simple tutorial we’re going to walk through how to add a custom link to the WordPress Admin Toolbar. Once we’ve added the basic link, we’ll enhance the appearance by adding a supporting Dashicon and use the plugin in a real-life example.

Before we start, one thing you will need to consider is which WordPress users should be able to see and access the custom link as we can restrict this later on in the tutorial.

Creating the Initial Custom Link

To begin with, adding the custom link to the navigation is relatively straight forward. Simply add the following code to the bottom of your theme’s functions.php file and customise the various fields which I’ve highlighted and commented:

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

function custom_wp_toolbar_link( $wp_admin_bar ) {
	if( current_user_can( 'level_5' ) ){ // Set the permission level or capability here for which user tier can see the link.

		$args = array(
			'id' => 'james', // Set the ID of your custom link
			'title' => 'James\' Link', // Set the title of your link
			'href' => 'http://www.starwars.com/', // Define the destination of your link
			'meta' => array(
				'target' => '_self', // Change to _blank for launching in a new window
				'class' => 'james-link', // Add a class to your link
				'title' => 'James\' link to Star Wars' // Add a title to your link
			)
		);
		$wp_admin_bar->add_node($args);

	}
}

Notice line four where I’ve restricted the link from appear unless the user has level_5 access or above (the user is an editor or administrator). To learn what access levels are available, take a look at WordPress’ Roles and Capabilities page.

If you’re happy with a simple text link, you’re perfectly fine to leave the above function on your theme’s functions.php file. However if you’re looking to enhance the link by adding an icon, I’d recommend packaging this functionality into an custom plugin.

Adding a supporting Dashicon

In order to add an icon, we’ll need to write some CSS to target our new link and display an icon of our choosing. We’re going to move our functionality into a custom plugin, so start by creating a new folder within /wp-content/plugins. Name the folder ‘custom-wp-toolbar-link’ and create the following two blank files within:

  • custom-wp-toolbar-link.css
  • custom-wp-toolbar-link.php

Within the custom-wp-toolbar-link.css file, add the following CSS. You can also pick a Dashicon by grabbing the ID from this page.

#wpadminbar #wp-admin-bar-james .ab-icon:before {
    content: '\f484'; // Change to a Dashicon of your choice
    top: 3px;
}

Be sure to change the ID wp-admin-bar-james to wp-admin-bar-XXX to match the ID of your custom link.

Bringing it all together

Now that we’ve created the supporting styles, there’s two things we need to do. Add the necessary icon spans to our link and only add the new stylesheet when the toolbar is active for the right users. Here’s my complete plugin:

<?php
/*
Plugin Name: Custom Admin Bar Link
Plugin URI: http://www.creare.co.uk
Description: This simple plugin adds custom link to the Admin Bar Menu with the option of having a supporting icon.
Version: 0.1
Author: James Bavington
Author URI: http://bavington.co.uk
*/

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

function custom_wp_toolbar_link( $wp_admin_bar ) {
	if( current_user_can( 'level_5' ) ){

		$args = array(
			'id' => 'james',
			'title' => '<span class="ab-icon"></span><span class="ab-label">'.__( 'James\' Link', 'some-textdomain' ).'</span>',
			'href' => 'http://www.starwars.com/',
			'meta' => array(
				'target' => '_self',
				'class' => 'james-link',
				'title' => 'James\' link to Star Wars'
			)
		);
		$wp_admin_bar->add_node($args);

	}
}

add_action( 'admin_enqueue_scripts', 'custom_wp_toolbar_css_admin' );
add_action( 'wp_enqueue_scripts', 'custom_wp_toolbar_css_admin' );

function custom_wp_toolbar_css_admin() {
	if( current_user_can( 'level_5' ) ){
	    wp_register_style( 'add_custom_wp_toolbar_css', plugin_dir_url( __FILE__ ) . 'custom-wp-toolbar-link.css','','', 'screen' );
	    wp_enqueue_style( 'add_custom_wp_toolbar_css' );
	}
}

Notice on line 18 where I’ve added additional spans and classes to the title to be able to use a Dashicon. And that’s it! If the functionality isn’t working, ensure that you have activated your new plugin and check the references to any IDs or titles that you rename to create your own custom link.

Real life example

Adding custom links to the Admin Toolbar can create convenient short-cuts to the areas of WordPress you access the most. In a live example below, I’ve added a link to the Customer Orders grid on a WooCommerce website.

woo-example

I’ve stored the slightly adjusted code for this example as a Gist over on GitHub.

  • B2 Marketing Ltd

    Thanks for this. Great tutorial that covers everything including custom and non-custom link as well as adding icon to the item.