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.

Navigation

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.

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.

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.

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.

Toolbar

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.

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.

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?