Create an Options Panel for your WordPress Theme

Building Advanced Theme Options Page using a Framework

I’ve recently been dabbling in theme development and it wasn’t long before I found myself wanting to create a theme options page, so that the end user could customise their theme without having to worry about messing with all the code.

I looked at a few options, including building a theme options page out of raw code, but to be honest, the information was a little spotty and not very helpful, so I quickly abandoned that solution.

Then, I thought to search for a Theme Options Framework and it wasn’t long before I was looking at Options Framework by WP Theming.

I wasn’t expecting much, given how inconsistent tutorials and advice had been on the matter up to this point, but my attitude quickly turned around; it looked great, worked well and was incredibly easy to set up. I love the features like the image uploader, hidden fields and color picker.


There’s a couple of different ways to install this framework; as a theme, or as a plugin. I’m going to show you how to build it directly into your theme.

Download the latest version of the theme from Github – you’ll find a link from the Options Framework Theme page. Now, you’ll notice that I’m referring to it as a theme and that’s because, at this point, it still is a theme; they’ve built it with a very simple theme, merely to demonstrate how the options work and how to call upon option values in your theme. You can also use it as a starting point for your theme. However, I’m going to assume that you’ve already started your theme, or you’re building it into an existing theme.

Once you’ve downloaded it, copy the /inc/ directory and options.php into your theme. Then, go to your theme’s functions.php file and copy the snippet from the Framework theme’s functions.php file to the very top of your theme’s functions.php file. This calls upon the framework and allows you to use the options within your theme. Everything is now installed as it needs to be.

Defining options

Now you want to start building your options page. Fortunately, they’ve made the process very simple; they haven’t gone as far as to provide an interface, because that would be unnecessary bulk, but they have laid out a template which is very easy to copy.

You have a whole bunch of options to choose from for the kinds of fields in your theme options page. You can use:

  • Text field
  • Text area
  • Checkboxes
  • Drop-down selection
  • Radio buttons
  • Upload function (for images, logos and the like)
  • Images (instead of radio buttons)
  • Background
  • Multiple checkboxes
  • Color picker
  • Typography
  • And a WordPress editor window

That should just about cover all bases! There’s literally nothing you can’t do with all of these options available to you. OK, so now to show you how to build them.

Open up the options.php file we uploaded earlier in your theme editor. If you take a general look over the file, you’ll notice that in between the codey bits, theres an example entry for each option type that I just mentioned. There’s also section headers to split the settings up into tabs. If you go into your WordPress dashboard, you’ll notice that there’s a new menu item under Appearance called Theme Options, where you can see what everything looks like. It should look a little something like this:

WordPress Theme Options

If you look back at options.php, you can see how this section is formed by the code below, from options.php:

You’ll note that each option array has several variables to help you display the fields the way you want in the options page, with extra help in the comments. For example, for the small select box box, under class you’ll see that there are three avilable options: mini, tiny and small. So you can use these examples to help build your own options page with a variety of different fields, and organise them into tabs by using the heading type (at the top of the code above) to start a new tab.

Once you give it a quick go you’ll see how easy it is to use. One thing to be aware of is the ID. The ID is a unique identifier for that field, which you’ll call upon in your theme, so make sure that it is both unique and descriptive.

The std field also allows you to enter a default value, as guidance to the end user, though you also have the name and description fields to help the end user use the options correctly.

Using the options in your theme

Once you’ve built your options page and it’s looking the way you want it to, you’re ready to take those values and actually use them in your theme.

So, head to wherever you intend to use a value in your theme and open that file for editing. Now, to call that value from the database, all you have to do is paste the following piece of code:

That will echo the value for the given option id. And you can simply repeat that over and over again for all the different options. For example, to show a custom logo, you might have something like:

Note that in this instance, I’ve used a conditional if statement to only display the custom logo if that value is set. Otherwise, it falls back to just displaying the site title and tagline. I’ve also set a variable ($custom_logo) up front to avoid repetition of the longer code, calling the option from the database. I also imagine this would result in less calls to the database, which is a good thing.

Incorporating it into your theme

You’ll be glad to hear that Options Framework is 100% GPL, so even if you’re a theme developer, you can use this framework to build your options pages and distribute them as you wish, including selling them.

So whether you just want to make it easier to make changes to your own theme, or you want to build a fully-fledged options page for a large commercial theme, the Options Framework really is an excellent fit.

24 thoughts on “Create an Options Panel for your WordPress Theme”

  1. Konstantin says:

    No, Dave, please don’t. Please use the Settings API!

    Honestly, there is no good reason to use a “framework” rather then what WordPress has to offer in this regard!

    And if you really DO need something pre-written, take the _s options page and enhance it with Kovshenin’s tip.

    Do it with WordPress! ;)


    1. Konstantin,

      Thanks for your informative comment. Where were you three months ago when I needed you! I’d like to see how this formats the theme options page. Also, do you know if it has the field options that the framework does (particularly the more advanced stuff like image uploaders)?

      Thanks again, always appreciate knowledgeable insight.

      1. Konstantin says:

        Where were you three months ago when I needed you!

        LOL! Good question, I don’t know!

        Concerning field options: No, it does not.
        But: Twenty Eleven started out with a colorpicker implementation and I’m sure somewhere someone already came up with an image uploader for a settings field.

    2. Also, is there a particular reason for your staunch opposition to it (security? non-standard techniques?), or is it just that the “proper” way to do it is the Settings API?

      1. Konstantin says:

        Yes, yes, yes and yes. :)

        I review Themes for the repository, and quite few (too many IMO) use the options framework.

        Many Themes don’t have more than five options, so it doesn’t make sence to add all the overhead of an entire “framework” to the Theme, which they also have to maintain separately. And if they do have more than five options, they have an entirely different problem => see the current “Decisions > Options” discussion (while the number five is just meant as an example for not many :) ).

        When using the Seetings API, you’ll never run into problems with outdated markup (whis is constantly changing, btw), you don’t have to bother with adding and updating your options, your Users will have more trust in your Theme, merely just because your settings sceen looks like the rest of the admin. And you learn about WordPress.

    3. Brightweb says:

      And how about NHP Theme Options Framework or Option Tree?
      They use the right WordPress Settings API….

      1. Konstantin says:

        I still don’t understand why you would want to have so much overhead?

        Take the options page from _s as an example (again). This is a great starting point!

        Using a pre-made solution might save you time in the short run, but believe me, there will be the time when your framework limits you in implementing this one cool feature and you’ll have to rewrite the whole thing nonetheless.

        I went with _s‘ code as a boilerplate, tweaked it to my liking and haven’t touched it since. I copy it for new Themes that I set up, and add new callback functions when needed. I invested time once and can now use the results over and over again.

        Learning how the Settings API works, rather than how to set up the framework you use, will pay its dividends over time. And it will make you an even better developer.

  2. Interesting conversation, I saw Kovshenin’s original post a few weeks ago when he started blogging about the Settings API so, I asked him how I could gain a better understanding of the WP core – Kovshenin’s recommended ‘Professional WordPress Development’ I have to say I’m so grateful – the guy is a legend. The book is spot on! I’m understanding so much more and it’s exactly what I was after.

    1. That’s very interesting. I’m thankful for the recommendation and will definitely have to check that one out!

  3. Duffie says:

    Thank you very much for the informative article, it will clean up some untidy issues I have had. The Building Your Options page alone help enormously!

  4. Dave says:

    Great help. I was about to give up designing options panel. (newbie)

    Your post saved me a lot of time and helped solve a problem with a client :)

  5. Jack says:

    The options framework is great and it does use the Settings API!

  6. Kirsten says:

    I’m currently putting together a theme options page for a client’s theme.
    The Options Framework by Devin Price is quite handy and I love it. As the _s-Theme options are a bit too basic for my needs I went for the framework.
    After reading the comments above I wonder wether (or why) this might be the wrong choice as @Konstantin pointed out.
    So, what exactly is the difference between the approach of Devin and Automattic concerning the Settings API? What is it that makes Devin’s code more “vulnerable” in the context of further WordPress updates?

    The Options Framework has a few sophisticated options (like a colorpicker and image uploads) – maybe that’s the point.

    By the way I’m very aware about the overhead of most of the theme options panels.
    I mostly use it for very basic layout and styling options the client can’t do by himself.

  7. Kirsten says:

    I just found that Devin wrote something on his site (the question was wether the code uses the WP Settings API):
    June 18, 2012 at 4:18 pm
    Partially. Fields aren’t outputted in the standard Settings API way (tables), but otherwise yes.

    Um. I see.
    No, I don’t. Anyone?

    1. Well, if that’s the case, he’s saying that the security and committing to the database is performed using the settings API, however, he is manually creating the page and the fields instead of using the Settings API way to do it. In my opinion, there’s nothing wrong with that; it’s not the best way to do it, but that’s not as concerning as not using the Settings API for committing to the database, which is much more secure and less fiddly more to the point.

  8. Kirsten says:


    Thanks a lot, Dave.

    I already decided to use the Options Framework in my theme (because I have no time to work the other way out), but now I’m a bit more relaxed about it ;o)
    No, just wanted to learn something. Thanks to you, I did!

  9. Devin Price says:

    Hi Dave. Great overview of the Options Framework. If folks are interested, there’s also a video screencast:

    I agree with Konstantin that if you’re just adding a couple basic theme options, it makes sense to build your own. The _s options page is a great place to start, or you could also deconstruct Twenty Eleven. Those are both excellent examples.

    However, I disagree that rolling your own is always the best course. The Settings API takes some time to understand, and building complex options like image uploaders, color pickers and wp_editor can be quite difficult.

    I think this is especially true for front end developers who may be great at building most theme code: HTML, CSS, and Javascript- but don’t have as much experience with PHP. Less experience developers can make mistakes such as not properly sanitizing data, enqueuing scripts improperly, etc- the Settings API doesn’t magically make this happen.

    I’m not saying people shouldn’t learn, just that it takes a while. And if someone prefers to spend that time designing themes I think that’s fine. That’s why I originally built the Options Framework.

    In terms of code quality, I also think it’s pretty good. The data sanitization is tight, and it leverages the Settings API to register the settings page and output nonces. It also works well and is easily to set up. Most anyone can get an options page running it minutes.

    Is it perfect? Definitely not. There’s tons of enhancements I’d love to make. Extensible options, a new uploader, and betters support for the front end theme customizer are high on the list.

    If you want to help out or contribute, check out the project on GitHub. Appreciate the comments and support. Cheers.

    1. Harish says:

      Hi Dave,

      I have been stuck with this question and discussion for a while and after trying both options (Custom coding vs using option framework) I went ahead with Option framework.
      If you wish to learn using settings API, I would suggest downloading Standard Theme by Tom McFarlin.

      I decided to use Options framework as like WordPress itself, the developer behind it (Devin) has always kept his code up to date and is very fast and helpful in terms of support. In terms of overhead, there is not much.

      I have used it from more than a year for custom development projects and currently also using it for free/premium themes am developing.

      1. Yes, since writing this, I have been trying more and more to teach myself to do it the “right way” and use the Settings API. It’s a great starting point though for people who aren’t inclined towards strict coding.

  10. Kirsten says:

    Thanks, Devin, for your great work.
    I just added some theme options to two of my themes and it works like a charm. I think, its indeed the more complex options that make a difference.
    It’s not just a text field or a checkbox, it’ colorpickers and upload buttons that people want and need. Of course you can paste the url of a logo-file into a text field. But my clients simply have no idea how to get this url (My logo is an image, right? Why is she talking about this url thing?)
    Perhaps one day I know how to build an image uploader myself, but in the meantime I’m happy and grateful that there is Devin’s framework.

  11. shawn says:

    I started out with the options framework and then moved over to NHP framework. Mostly did the move because I liked the admin layout of NHP a little better having the tabs on the left. Other than that, they seem the same.

    One question:
    Has anyone found a framework that uses the settings api, that has repeating field groups?

    I use ACF for my metaboxes and the repeater field group is perfect, but I have yet to find one for the settings api. Don’t want/need a gui, just the logic.

  12. david says:

    AWESOME. Thank you so much for this!!!
    So I have my theme all done and it’s working great with the option page.
    My only issue is that on the THEMES page where it says:
    *Customize OPTIONS: Widgets Menus Theme Options Header Background*
    The Theme Options link is pointing to options.php instead of /wp-admin/themes.php?page=theme_options

    Any idea where to fix this? I’ve spent hours on it and am totally stumped…


  13. Denis says:

    Hi Dave, thanks alot for this, a few errors I’ve noticed though, you keep on referencing to “of_get_option” ,theres no function like that on optiontree,I believe the right function is “ot_get_option” ot not of.
    Also on your example code for displaying the custom logo on line three “”” you have closed the php function incorrectly “?/>” instead of just “?>” (without the backslash).
    Just a few things that can give a rookie developer a nasty headache.
    Apart from that, this is an awesome post. Keep it up :D

    1. Well, this is working with the Options Framework not optiontree, and at the time of writing, the function was definitely of_get_option. However, I do see the incorrect PHP tag: thanks for that. It’s fixed now :)

Leave a Reply