Thursday 8th January, 2015

Using a custom icon font for WordPress dashicons

There are number of tutorials out there on how to use WordPress’s built-in (from version 3.8) dashicons with your custom post type. But what if you want to use a completely custom icon font, such as those generated by Fontastic?

If you’re building a WordPress theme or plugin that has custom menus, custom icons for your new dashboard menu are a nice touch.

You’ve long been able to add custom images to your custom post type menu using the menu_icons parameter of register_post_type. And from WordPress 3.8, you’ve had the ability to use WordPress’s built-in dashicons icon font. But what if you want to use your own icon font, such as one generated by the fantastic Fontastic?

Let’s use the example of adding a new custom post type called ‘performance’ to a theatre company’s theme. I’m going to carry on using Fontastic, but you can easily adapt these instructions to any other custom icon font.

Grab a brew…

Go to Fontastic and spin up a new font. Click ‘modify font’ as we’ll need to give our icons a custom class:

There are two important bits here.

  1. Your classes need to start with dashicons. This is because the menu_icon property will interpret anything that doesn’t start with dashicons as a URL (which we don’t want).
  2. We need some way to group our dashicons (such as theatre in this example) in order to distinguish them in CSS from the built-in dashicons. If we don’t do this, we’ll end up conflicting with WordPress’s built-in dashicons.

Select the icons that you’d like to include and click ‘customize’. I find that’s it’s useful to give the icons the same name as our custom post type – in this case, performance.

Click ‘publish’ and click ‘download’ under the ‘Install Manually’ section.

The downloaded zip is pretty useful – it has the generated font in a variety of formats, along with a stylesheet that links it all up.

Drop the ‘fonts’ folder into your theme. You’ll also want the styles.css file – but rename it to dashicons-styles.css so that it doesn’t conflict with your theme’s stylesheet.

@charset "UTF-8";

@font-face {
  font-family: "theatre-company";
  src:url("fonts/theatre-company.eot");
  src:url("fonts/theatre-company.eot?#iefix") format("embedded-opentype"),
  url("fonts/theatre-company.woff") format("woff"),
  url("fonts/theatre-company.ttf") format("truetype"),
  url("fonts/theatre-company.svg#theatre-company") format("svg");
  font-weight: normal;
  font-style: normal;
}

[data-icon]:before {
  font-family: "theatre-company" !important;
  content: attr(data-icon);
  font-style: normal !important;
  font-weight: normal !important;
  font-variant: normal !important;
  text-transform: none !important;
  speak: none;
  line-height: 1;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

[class^="dashicons-theatre-"]:before,
[class*=" dashicons-theatre-"]:before {
  font-family: "theatre-company" !important;
  font-style: normal !important;
  font-weight: normal !important;
  font-variant: normal !important;
  text-transform: none !important;
  speak: none;
  line-height: 1;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

.dashicons-theatre-performance:before {
	content: "a";
}

This file is really handy – it’s saying if an element has a class that starts with dashicons-theatre-, use the font ‘theatre-company’. And, if it’s a performance (dashicons-theatre-performance), add the letter ‘a’ to the content (where the letter ‘a’ is mapped to the image of the hat in our font).

Now we’ll need to enqueue this style – but only if we’re in the dashboard. Here’s how it looks in this theme’s functions.php file:

// Add custom admin styles

function load_custom_admin_styles() {
wp_register_style( 'custom_dashicons', get_stylesheet_directory_uri() . '/dashicons_style.css', false, '1.0.0' );
wp_enqueue_style( 'custom_dashicons' );
}

add_action( 'admin_enqueue_scripts', 'load_custom_admin_styles' );

Now, we’ll need to register our custom post type. Here’s how it looks in this theme’s functions.php. Note that the menu_icon parameter is the same as the class that’s defined in dashicons_styles.css, in this case dashicons-theatre-performance.

add_action('init', 'register_performances_post_type');

function register_performances_post_type() {
	register_post_type('performance', 
		array(
          'label' => 'Performances',
          'description' => 'Our Shows',
          'menu_icon' => 'dashicons-theatre-performance'
		)
	); 
}

And ta-da! A fancy hat to go along with our Performances post type.