WordPress 2.5 Plugin Settings Pages Style Guide

February 23rd, 2008 – 38 Comments

Fellow plugin authors beware! Your plugin settings pages might look pretty awful in WordPress 2.5’s new admin theme… Currently, I’m working on making all my plugins work and look good in it, and I had to do a bit of research. There’s a page on migrating plugins and themes on the WordPress codex, which can help you a bit, but it doesn’t tell you anything about styling the settings pages.

With the new theme for the admin in WordPress 2.5 (whether you like or dislike it, it’s coming at you anyway), most plugins settings pages look pretty ugly… I’ve been working on my Robots Meta plugin and RSS footer plugin, and I’ll tell you what I know now about the styling of these pages.

The wrapper
Nothing changed here, your plugin settings page should still be wrapped in

<div class="wrap"> </div>

Headings should start with an h2 heading for the main heading, and h3’s for the subheadings. These look like this in my fixed Robots Meta plugin, h2 and h3:
Admin Headings example

Individual settings
The individual settings of the plugin usually consist of a name, an explanation and a setting input. To display those settings nicely, you’re “forced” to use a table. This table should have the following markup:

<table class="form-table">
 	<th scope="row" valign="top">Name</th>
 		<input id="inputid" />
  	 	<label for="inputid">explanation</label>

Groups of settings can be put into one row, to make stuff easier to understand. Settings then look like this:
Settings example

Submit buttons
The last thing on your pages is a submit button, and these also still look the same:

<span class="submit">
  <input name="submit" value="Save Changes" type="submit" />

Which creates the following button:
Save Changes button

If you create your plugin settings pages like this, they should look good for everyone!

38 Responses

  1. Trevor Fitzgerald
    By Trevor Fitzgerald on 24 February, 2008

    The niceblue class just got a name change: http://trac.wordpress.org/changeset/7000

  2. youfoundjake
    By youfoundjake on 24 February, 2008

    Hey Joost,
    Yeah, I’m a bit nervous about the 2.5 update coming.. As we get closer, I’m going to get a post up about some of the details and what it may effect in terms of plugins as well as themes. Man oh man, I’m not looking forward to this update. Maybe I should wait 6 months like I did with XP Service 2. Heeh.

  3. Joost de Valk
    By Joost de Valk on 24 February, 2008

    @trevor: Thx, fixed it.

  4. Andy
    By Andy on 24 February, 2008

    The problem here is that a class like “form-table” for example, does not exist in pre-2.5 admin CSS. I can see I can create admin displays that conform to 2.5 but they may look a mess in pre-2.5 systems because of this.
    And that is one of the reasons I tend to define my own CSS for admin display – because WP so often just removes or changes stuff like this without a word of warning and with no consideration to the existing body of work.

  5. PublicRecordsGuy
    By PublicRecordsGuy on 24 February, 2008

    All these upgrades are very daunting for the newest member to the blogging community. I went from a blogspot blog to wordpress, paid to get my theme designed and coded. It’s scary to see that it keeps changing.

  6. Andy
    By Andy on 24 February, 2008

    Your ‘front-end’ theme should be fine. All the changes and re-design are in the admin pages.

  7. Joost de Valk
    By Joost de Valk on 24 February, 2008

    @Andy: you could just do a conditional insert of some CSS if you’re pre 2.5…

    @PublicRecordsGuy: your theme should indeed be ok, and I understand it’s daunting, but this is WordPress’s first admin overhaul EVER.

  8. Andy
    By Andy on 24 February, 2008

    Oh yes. We are having to do this with code that places a new item on the write post screen (2.5) – anything to do with categories (2.2 at the primitive level) – any direct access to ‘page’ records (2.1)! The list gets longer and longer. There are so many conditional statements it just gets tiring.

    This was a good starting off point and useful for which I thank you. Since I left the comment I have been doing exactly what you sugest and it’s a slow, boring slog!

  9. Joost de Valk
    By Joost de Valk on 24 February, 2008

    Hehe Andy, I know, I’ve got 10 plugins to update as well, and they’re still sometimes changing the CSS on trunk, so it’s not even stable yet…

  10. Jermayn Parker
    By Jermayn Parker on 28 February, 2008

    I am not a Plugin developer but rather a Plugin user so I appreciate the effort to make the transition good for people like me :D

  11. Matt Thomas
    By Matt Thomas on 29 February, 2008

    The problem here is that a class like “form-table” for example, does not exist in pre-2.5 admin CSS. I can see I can create admin displays that conform to 2.5 but they may look a mess in pre-2.5 systems because of this.

    2.5 brings with it some unique form and table styling, and those styles shouldn’t be applied by default to pre-2.5 Plugins. I experimented with CSS that applied the new form-table styles to fieldset tables, actually. The styling looked fine in many themes, but looked terrible in some popular ones. Adding a new class (that should stick around in future releases) allows Plugin authors to choose it if they wish, and rely on it to deliver a style consistent with the rest of the UI in the future.

    Thanks for the write-up, Joost!

  12. Keith Bowes
    By Keith Bowes on 2 March, 2008

    Is there some reason why one can’t use CSS to style the options page instead of resorting to a layout table? Is it just a problem with browser support?

    Also, you can use more than one class on each element:

  13. Keith Bowes
    By Keith Bowes on 2 March, 2008

    LOL, I forgot to escape my HTML bad me. It’ll be visible if you edit my comment. Also, I do have a gravatar, but it’s not showing up here.

  14. ChaosKaizer
    By ChaosKaizer on 3 March, 2008

    Just a suggestion with “form button”.

    <span class="submit">
    <input name="submit" value="Save Changes" type="submit" />

    span is inline-block element it should be replace with block element like P or DIV for wrapping form elements.

    better write it up like the following

    <button type="submit" class="submit" title="<?php _e('Save Changes'); ?>"><?php _e('Save Changes'); ?></button>

  15. m0n5t3r
    By m0n5t3r on 5 March, 2008

    actually, it looks like it’s not a span, it’s a <p class=”submit”> surrounding the submit button

    also, since “options” was renamed to “settings”, new-style option page hooks will have to be renamed from something like “options_page_my_plugin” to “settings_page_my_plugin” (I chose to add both, to keep compatibility with older versions).

  16. Epic Alex :: Web Design
    By Epic Alex :: Web Design on 8 April, 2008

    Hey Joost,

    Just in case you haven’t come across it, I have written a post in response to this one that goes into a bit more detail about some of the other options available for displaying plugin options, check it out here: