How to Add Dashicons to Your WordPress Theme or Plugin

With the revamped WP-Admin in WordPress 3.8, a brand new set of icons called Dashicons was introduced. Dashicons, designed by Mel Choyce, were created to enhance the new WP-Admin UI, from the Content Screen Editor to the Administration Menu, as shown in the screenshot below.

Since WordPress uses Dashicons for icons in WP-Admin, you should consider using them in your themes and plugins as well. Font icons like Dashicons allow you to easily customize the output through CSS. If you are a developer looking to update your plugins or themes to align with the latest WordPress design and its new features, this article is for you.

Using Dashicons in the Administration Menu

If you incorporate a Custom Post Type into your theme or plugin, you can use Dashicons for your icons. Custom Post Type uses menu_icon to display the icon. Before WordPress 3.8, you could add your image icon path. From version 3.8 onwards, this parameter can also declare an icon from Dashicons.

First, visit the Dashicons website. Click on an icon. You will see the selected icon reflected in the header, displaying the icon’s name with options to copy it in several formats: CSS, HTML, and Glyph.

Copy the icon’s name, and add it in the menu_icon of your Custom Post Type function, like this. I’ve kept the code brief for this article. The full code can be found here.

$args = array(
    'label' => __( 'book', 'book' ),
    'description' => __( 'Post Type Description', 'book' ),
    'labels' => $labels,
    'supports' => array(),
    'taxonomies' => array( 'category', 'post_tag' ),
    'menu_position' => 20,
    'menu_icon' => 'dashicons-book',
    'capability_type' => 'post',
);

In this example, I’ve created a Custom Post Type for posting Books. As you can see below, the book icon appears beside it.

Menu Page

Plugins can also use the add_menu_page function to add an Administration Menu. In this case, you can specify the Dashicons icon name as the sixth parameter. In the following example, we will display the “wrench” icon on our Options page.

function hkdc_custom_menu_page() {
    add_menu_page( 
        'Options Page', 
        'Options', 
        'manage_options', 
        'myplugin/option.php', 
        '', 
        'dashicons-admin-tools', 
        81 
    );
}
add_action( 'admin_menu', 'hkdc_custom_menu_page' );

Head over to WP-Admin, and you should see the icon as shown.

The Fallback

Never assume that all your users will update to the latest WordPress version. In some cases, they won’t. They may have installed a plugin to disable automatic updates. Therefore, it’s necessary to provide a fallback to support older WordPress versions. If we don’t, the icon will appear as a broken image (as shown in the image below, next to Books).

Before proceeding, ensure that you have placed the image icon in your theme or plugin directory. Then, you can specify the icon with a conditional function, as follows:

First, set the default to use Dashicons.

$icon = 'dashicons-book-alt';

Replace the $icon variable’s value if the WordPress version is 3.7 or below.

if (version_compare($GLOBALS['wp_version'], '3.8', '<')) {
    $icon = get_template_directory_uri() . '/extra/img/book-brown.png';
}

Next, replace the icon parameter in the Custom Post Type (as well as in the add_menu_page function) with the $icon variable.

$args = array(
    'label' => __('book', 'book'),
    'description' => __('Post Type Description', 'book'),
    'labels' => $labels,
    'supports' => array(),
    'menu_position' => 20,
    'menu_icon' => $icon,
);
register_post_type('book', $args);

And that's it. It will use Dashicons for WordPress 3.8 and later, while displaying the "image" icon in older versions.