Problem: I want this dashicon as a admin menu icon!

You have written a plugin. Your plugin adds a new top level menu item to the WordPress‘ admin area. And you want to change the generic dashicon with your favorite one. But you don’t know how?

It is dead easy! This tutorial shows you the simple ways.

Solution: Three ways to set the dashicon of your menu item

1. Write the CSS and print it out

The code pattern

First paste the following code into your plugin main file and change some things as described in the following text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?php 
/**
* Print icon for top level menu item of this plugin
*
*/
function abc_display_menu_icon(){
print '<style type="text/css">';
print '#toplevel_page_menu-slug .dashicons-admin-generic:before {';
print ' content: "\f232";';
print '}';
print '</style>';
}
 
/*
* Add function  to the admin_head hook
*
*/
 
add_action( 'admin_head', 'abc_display_menu_icon' );
<?php 
/**
* Print icon for top level menu item of this plugin
*
*/
function abc_display_menu_icon(){
print '<style type="text/css">';
print '#toplevel_page_menu-slug .dashicons-admin-generic:before {';
print ' content: "\f232";';
print '}';
print '</style>';
}

/*
* Add function  to the admin_head hook
*
*/

add_action( 'admin_head', 'abc_display_menu_icon' );

Change 1: Set the desired icon

The first thing to change is, of course, the icon value in the line.

1

print ' content: "\f232";';
print ' content: "\f232";';

How to get the value of your desired icon? Go to this great dashicons resource developer.wordpress.org. There you will see all WordPress supported icons and their CSS values.

Clicking on the desired dashicon

  1. On this page click on your desired icon
  2. and click on the link ‚Copy CSS‘ in the header section.
  3. A dialog box appears containing the CSS line with the content value of your icon.

    Copy the whole line into the clipboard
  4. and overwrite the content line in your PHP code with the copied line.

Now you have the desired dashicon in the CSS code. But this will not work for now. You have to change the CSS selector.

Change 2: Set the correct CSS selector

The second thing you have to change is the CSS selector. Find out the CSS selector to point to you menu item correctly. There are two ways:

  1. You can assume the selector name with the formula #toplevel_page_ + $menu_slug. $menu_slug is the string you passed as a parameter to the function which creates your top level menu item ( ‚add_object_page()‘, ‚add_menu_page()‘ etc.).
  2. The second way is:
    Screenshot CSS Selector
    Look into the HTML code of the admin page, search for the code of your menu item and pick the value in the id-attribute of the list item.

If you have find out the correct name of the id change the string

1

#toplevel_page_menu-slug
#toplevel_page_menu-slug

to the new name. Keep the hash at the start of the string.

Change 3: Alter the function name

The third and last step: Change the prefix ‚abc_‘ in the function name to something other string which is unique. A good rule of thumb is to take the first letters of your plugin name, for example ‚My special plugin for WordPress‘ will result to ‚mspfwp‘, thus the new function name will be ‚mspfwp_display_menu_icon‘.

Of course you can change the whole function name completely to your taste.

Change the string in the function name and in the second parameter of the add_action() line.

The OOP way

If you want to use this trick in a PHP class, just take the previous written code, walk through the steps 1 to 2 and do two slight changes:

  1. Paste the function code anywhere in your plugin class. Set the access status of the function to ‚public‘, resulting to the line 
    1

    public function display_menu_icon(){
    public function display_menu_icon(){
  2. Set the add_action() line into the constructor method __construct() and change the second parameter from a string to an array referencing to the class instance: 
    1

    add_action( 'admin_head', array( $this, 'display_menu_icon' ) );
    add_action( 'admin_head', array( $this, 'display_menu_icon' ) );

And your work is done!

You can find an example in the PHP code of my plugin Quick Featured Images at the WordPress Repository.

2. Special case: Custom post types

If your plugin uses its own custom post type chances are high that you use the WordPress function register_post_type (). This function expected some parameters. One of them, called ‚menu_icon‘, allows you to define the menu icon for the menu item of the custom post type.

The ‚menu_icon‘ parameter passes either an url to the icon file, a base64-encoded SVG code, ’none‘ for no icon or  the name of a Dashicons helper class to use a font icon, e.g. ‘dashicons-chart-pie’.

To find out the CSS selector name for your desired dashicon

  1. go to http://melchoyce.github.io/dashicons/,
  2. click on your desired icon,
  3. then click on the link ‚Copy HTML‘ in the head section of the page.
  4. A dialog box appears with a HTML snippet, for example 
    1

    <div class="dashicons dashicons-admin-links"></div>
    <div class="dashicons dashicons-admin-links"></div>

    It contains the class attribute with two values like „dashicons dashicons-admin-links“.

    Take the second value as the value for the parameter ‚menu_icon‘.

You will find detailed informations about ‚register_post_type()‘ in the WordPress Function Reference.

3. Special case: Icon by the WordPress function add_menu_page()

Maybe the collection of dashicons does not contain the icon you want to use as the menu item for your plugin. In this case you can produce your own icon image file and use this as the menu icon and tell the function ‚add_menu_page()‘ the URL of your icon file. The icon image should not be bigger than 20 x 20 pixels.

The WordPress function ‚add_menu_page()‘ creates a new top level menu item in the admin area. One of their parameters passes the URL to your icon file.

1

$page_hook = add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );
$page_hook = add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );

You will find detailed informations about ‚add_menu_page()‘ in the WordPress Function Reference.

Discussion

What do you think about these solutions? Did you find other ways to set the menu icon? You can write down your thoughts as comments here.

11. Juli 2014  
      , , , ,