Add an Icon to a WordPress Widget

The Proposal

Just recently I was working on a plugin and a part of that plugin had a custom widget. The website I was developing the plugin for had so many widgets in the widget area, that it became increasingly difficult to locate my custom widget amidst all the others. I was thinking of possible ways that I could distinguish mine from the rest. I noticed all of the pretty icons in the admin dashboard menu, and it hit me. Why don’t any widgets have custom icons associated with them? It couldn’t be all that difficult to add in icons to widget area, much like your able to when registering a custom post type, or adding a parent menu through a plugin.

So, off I set to find a way to add a custom icon to my widget. If you wan’t, follow along with me while I discuss how to add an icon to a WordPress widget.

Steps Taken

So, lets begin by registering our custom widget. I’m simply copying and pasting this directly out of the WordPress Codex. Remember this all goes into your functions.php file of your theme or child theme.

Now, if you go into the Widgets area in the dashboard via the appearance menu ( ‘Appearance > Widgets’ ) you will see our newly registered widget. It’s a very basic widget, don’t worry about the functionality. I’m just going to show you how to add an icon to the newly created widget (But you can do this with any widget that’s installed on your site.).

If you right click and check the ID associated with the widget, we’ll see that its ‘widget-8_mynewwidget-__i__’. We can use this to target our widget , and use CSS to add an icon to the right of the title. That way we’ll easily be able to spot our widget, and any plugins we create for the repository, that has widgets, will really stand out.

Here were going to write a custom function in the functions.php file that will load a style into the admin area that will control our new widget. But remember, if your writing a plugin this should be added to your plugin’s main file. If your adding this to a theme, you can also conditionally load a css file into the dashboard area, but were just going to write a function. You can copy and paste the function into your file exactly as it is. Remember to change “Your-Image-Here.png” to the correct path to the image you want to use.

I’ll breifly explain what were doing here. If you know what’s going on, you can skip ahead. I just like to explain for anyone who’s learning as we go. The function is named add_icon_to_custom_widget. As you can see at the bottom, we’ve hooked into the action admin_head, which means that anytime admin_head is fired, our function will fire as well.

We’ve taken it one step further and appended ‘-widgets.php’ to the end of the admin_head hook, which is telling WordPress to only fire our function on the widgets.php page. And above that is our styles that are printed out in the section on widgets.php.

Our style, *[id*=”_mynewwidget”] is saying, target ALL elements with the ID containing _mynewwidget in the name. We’ve done this, because our widget could really be registered anywehre, and when its registered in different locations a different number is added to the name. So I’ve gone ahead and made sure no matter where our widget ends up among all the other widgets, we can still target it.

After you’ve successfully changed the path to your image, go ahead and save your functions.php file and take a look at the widgets page. You should now see your image next to our newly registered widget.

If you want, you can use one of the included SVG icons that come packaged with WordPress. Check out all the dashicons gathered by Mel Choyce, http://melchoyce.github.io/dashicons/. There are a lot of cool icons included, and more are on the way for 3.9!

Here’s the code you’ll need if you want to go with a dashicon:

Notice we’ve added a font-family attribute, and we’ve changed the content attribute to the matching unicode for the icon. We’ve also added a font-size attribute, and upped it to 22px. Which you can get by clicking ‘Copy CSS’ at the top of the dashicon page. You’ll need to adjust the font-size and the margin to get the new icon to sit properly, but it shouldn’t take too much tweaking.

Conclusion

We’ll there you have it. We were able to successfully add a custom icon to a widget on the widgets page. I feel this adds yet another layer of customization to plugin and theme developers, and should possibly be included into a new patch in core. As I mentioned earlier we can add our own icons to newly added dashboard menus such as custom post types and any menus you add through a plugin.

Example:

I’m proposing a patch be added to core that would allow much the same when registering custom widgets. I’m not sure how we’d go about achieving it through a patch, but it is definitely do-able, and I’d love to have that feature.

Update – 8.27.2014

Since originally writing this post I’ve come across a ticket in trac that proposes the same idea. I took it upon my self to take the first stab at submitting a patch to core that would add such functionality. You can see the ticket here.

About the Author

Evan Herman

Evan is a full time WordPress developer at Yikes Inc. where he makes all sorts of cool things with WordPress. When he's not there you can find him developing awesome plugins, blogging about WordPress or hanging out with his three cats and amazing girlfriend in Philadelphia, PA.