WPCandy’s Completely Unofficial Guide to Plugin UI


On the 29th episode of the WPCandy Podcast we talked about the sometimes poor state of plugin user interfaces. Many WordPress plugins are inconsistent with the native WordPress user interface in how they implement settings in the administration area for users.

I’m writing this guide to outline a (completely unofficial) set of best practices for implementing settings pages that is consistent and current with the native WordPress administration user interface. I’ve based these guidelines on my observations and experiences with using plugins in WordPress. They’re also totally a work in progress—if you have suggestions, feel free to add them in the comments section.


When utilizing the Settings API it is important to place the link to your plugin’s settings page appropriately, otherwise a user with even a moderate amount of plugins installed can get confused about where each settings page is.

As a general rule of thumb, unless your plugin adds significant functionality to WordPress, it should sit as a secondary item under the general “Settings” panel. If you aren’t sure what significant functionality means, ask yourself if your settings page has multiple pages and/or includes options to manage or view content that a user will need to navigate to often. These are only guidelines, of course, and answering “yes” to any of these questions does not mean that your plugin needs its own top-level entry.

Proper placement of navigation.

Above you can see two plugins that following this guideline correctly. The form plugin adds a new type of content, with settings to view and manage all that content. The plugin appropriately take a place as a top-level menu item. The caching plugin’s developer correctly determined that the page would not be accessed often enough to call for a top-level item.

If you do choose to include your plugin’s settings as a top-level menu item, you should consider where in the list it will go. The side panel is loosely divided into two sections: content management (top) and settings (bottom.) Where you put your panel should depend on what category it falls under. Placement within these sections is at the plugin author’s discretion, though it is probably best not to place your panel in a spot that disrupts the location of commonly used panels such as the Posts Screen. This can mean placing the panel above or below such items, depending on what section you’re in and what you’re trying to avoid.

Improper use of colored icons

When setting up your admin menu icon, keep in mind:

  • All icons should stay monochromatic gray until the user hovers over the panel. This is easily the most overlooked design convention of the side panel. Being the only colorful spot on the sidebar draws undue attention to your settings panel and distracts users.
  • If you choose to display a colorized version of your icon on hover, try to use the same color palette that the other icons do. Use a color picker to find the hex codes in use on the menu.
  • Try to use an icon that resembles the feel of the other icons. Please see the aforementioned form plugin to see this in action. If you can’t do this, it might be helpful to choose one of the default icons that is closest to what your plugin does.

Tertiary Tabs

If your plugin is complex enough to call for options spanning multiple pages but does not meet the criteria for creating a top-level panel, you should create a tabbed navigation on the settings page itself. This is a native WordPress user interface element that you can see in use on the Themes Screen. The developer of the aforementioned caching plugin has used this method correctly on his settings page, albeit with one abnormality.

Tabbed navigation

He has placed the title of the settings page above the tabbed navigation, as opposed to the left of it. This is acceptable in cases (and probably this case) where the title and tabs might be too wide and create a horizontal scroll bar for users on smaller screens. However, best practice is to put the heading (with an icon/logo) of the settings page to the left of the tabs. Below is the general markup of the tabbed navigation with the heading added in its correct place.


The bar at the top of WordPress is a relatively new feature (a new form since 3.3, actually) meant to provide shortcuts to common actions in the admin area. It encourages plugin authors  to take advantage of this feature as a means of improving their plugin’s usability.

If you do choose to add an action to the bar, make sure that it is one that really belongs there. For instance, the author of the aforementioned cache plugin added an action to clear the cache to the admin bar in his latest update. This is easily the most common reason people navigate to his settings page and he saved people a bit of time. Do not assume that your plugins needs an entry on this bar, and please don’t add most of your plugin’s functionality to this bar.

If you believe you’ll have a few of these actions, create a drop down menu.

Dashboard Widgets

The dashboard’s purpose is to give users a quick look into important information on their WordPress installation. It is not meant as a way for you to advertise your services to users or publish a news feed from your site that is only tangentially related to the plugin itself. Although dashboard widgets are easily hidden and rearranged, not every user has the technical skill to do so. Please consider heavily whether or not your plugin really needs a dashboard widget before creating one. Another idea is to have the widget be opt-in, so that only users who explicitly want it have it.

If you decide to create a dashboard widget, the colors and styles should be consistent with the rest of the WordPress admin UI. The widget should attempt to display all pertinent information in the most efficient space possible. As usual, try to look at the standard widgets to get a feel for how yours should look.

Design of Settings Page

It should go without saying that the design of a settings page is extremely important to a plugin’s usability. While inventing interesting and unique interfaces might be a little much to ask of plugin developers, it is possible for every plugin to at least include a competent user interface by following a few guidelines.

Options page that is inconsistent with admin UI.

In general, keep this tips in mind for your settings pages:

  • Make your page free of any custom elements that clash with the native WordPress administration UI.
  • Infer structure of pages from WordPress core settings page designs. Be on the lookout for updates in this UI with each major version release.
  • Use native WordPress IDs and classes for form elements. Not doing this is the number one way to have a bad settings page.
  • Try to consider real use case scenarios when laying out the options. Not every single thing has to be changeable or customizable.
Ryan also wrote up an editorial on this topic a few months back that generated quite a bit of discussion.

That’s it!

Still with me? Excellent. This completes a basic primer of plugin user interfaces. If you like the guidelines, be sure to check every plugin you submit against them and hopefully we’ll be on our way to a better WordPress experience for everybody.

Do you have any tips for plugin developers that aren’t listed above? Have you run into any inconsistent UI practices that are worth warning against?

22 thoughts on “WPCandy’s Completely Unofficial Guide to Plugin UI

    • Ha, yeah. I have a plugin I’ve rolled for myself that does nothing but kill the various plugin-added widgets that I’ve discovered. Think there would be interest in, say, Dashboard Widget Zapper, a plugin that does nothing but clear out any commonly annoying widgets added by plugins?

      • What I’d like even better is a way to disable dashboard widget registration by plugins in general. Give it arguments so that you can have exclusions of course, but that way you don’t have to add them every time you add a new plugin with dashboard widgets.

      • You do realize that you can just uncheck them from Screen Options on the dashboard to hide them? Granted this is per-user and doing it via a plugin would kill it for all users.

      • I’m glad to hear I’m not the only one clearing out a long list of dashboard widgets. Brian Krogsgard’s idea to disable them all except a whitelist is a stroke of genius!

  1. Pingback: Marketing Day: January 12, 2012

  2. Is there a way to have the menu icon change on hover? I’ve tried using sprites but I never could get it to work.

    I thought when assigning an icon (such as in a CPT) the hover state os 100% opacity while the normal state is something around 70%.

  3. Pingback: Basic Guide On Creating Plugin UI

  4. It would be ideal to remove dashboard widgets from all plugins. But wait a minute… What does Yoast get for creating and supporting a superb high quality plugin such as WordPress SEO by Yoast….. It has had 870k downloads. Had everyone who had downloaded it given him $0.99 donation (iOS economy) … it would certainly justify the amount of time he spends on it…. But guess what. Donations hardly pay for the time that you spend on plugins (let alone countless support / feature requests).

    I have heard the argument of keeping your blog’s RSS into your plugin’s settings page. But how often is that page visited??? Putting it in the dashboard at least gets Yoast some impressoins to his site.

    What would be ideal if plugin authors can easily hook into the Other WordPress News tab and simply insert their feed there. Some might say what if its their personal blog where they talk about dev sometimes… Well Ma.tt is in there and he sometimes blog about personal stuff as well. It would be great if we can add multiple RSS feed sources so along with planet, it also adds Yoast or any other author.

    Alternative idea: Lets create an iOS like marketplace in the WP Plugin Repository. To be in there you give 30% cut of the sale to the WP Foundation. That money can go to towards funding WordCamps and local WordPress meetup groups and even encourage WP development among kids by having classes and such. All the money that goes from the dev to the foundation will be treated as a donation.

  5. Hi,

    thanks for the great article!

    Can you please tell me the name of the “Forms” plugin the screenshot below the “Navigation” subheading? I can’t find it 🙁

    Thanks a lot!

  6. Pingback: Do You Want To See Plugin Specific Dashboard Widgets Disappear?

  7. Pingback: WPCandy’s Completely Unofficial Guide to Plugin UI | Theme Options Gallery

  8. Pingback: WordPress Plugins and Usability – a Match Made in Hell?

  9. Pingback: Headline Split Testing for WordPress - WPMU.org

  10. Thank you for pointing out that sidebar icons should be monochrome! After that was pointed out to me, I felt like I was living in http://xkcd.com/1015 (if you really hate someone, teach them to recognize bad kerning). The only reason I wrote the Monochrome Admin Icons plugin was to save myself from twitching every time a new plugin with color icons was installed. Matching icons for all!!

Comments are closed.