The Options Framework Theme has all the code included to build a out a full featured options panel. It’s a bundled version of the Options Framework Plugin for those folks who want to build the options directly into the theme (rather than relying on a plugin).

This project was released long before the Customizer was a part of WordPress. The Customizer is now the recommended way to add theme options and you can read more about it here.

Available Options

  • text
  • textarea
  • checkbox
  • select
  • radio
  • upload (an image uploader)
  • images (use images instead of radio buttons)
  • background (a set of options to define a background)
  • multicheck
  • color (a jquery color picker)
  • typography (a set of options to define typography)
  • editor


Copy the “inc” directory, options.php, and the code snippet in functions.php from the “Options Framework Theme” into the theme of your choice. Hack away. You can also watch the video above to see how it is done.

When to Use Theme Version vs. Plugin Version

The code is 99% the same between the plugin and theme version. If you can do what you need with the plugin version, I think that’s the best route. If you find that you need to make significant modifications that aren’t possible with the plugin, go ahead and use the theme version.

Change the Menu Location

It’s highly recommended that you leave theme options under the “Appearance” menu where users expect them.

But, if you do decide to change the menu location it will break the media uploader. This is because the media uploader scripts are enqueued on $of_page= ‘appearance_page_options-framework’ in options-medialibrary-uploader.php. If you change the name or location of the menu, you’ll need to update the hook to be accurate, e.g. $of_page= ‘toplevel_page_options-framework’ and those scripts will load properly again.

Sanitization Filters

If you’re interested in how the options data is verified, or if you’re wondering why your script and embed tags are stripped out in the Options Framework, read this post.

Can I Use This Code in Commercial Themes

Yes! This code is 100% GPL. Please read the included license for more details.

Development Version on GitHub

The development version of the Options Framework Theme is available on GitHub.

Additional Tutorials

The demo themes associated with these tutorials are also available on GitHub.

862 thoughts on “ Options Framework Theme ”

  1. Hi Devin,

    Awesome coding you’ve done here!

    Can I just check though – in your example index.php for the ‘options check’ template ( you have the options called like the following:

    If no entry is made for a given option, should this output the ‘no entry’ text (similar to the way get_option outputs a default)?

    The only way I can get a simple default value to show at present is using something like:


  2. Hello Devin,
    I’m loving this, really great job.

    I have a question if it’s OK to ask.

    I added 10 options of the type “text” where the user needs to fill URLs.
    They are not mandatory. Meaning, the user will fill the text fields that are relevant for him.

    In the theme itself, I check each of these field, and if they are not empty, I display their output.

    What I want to accomplish is letting the user to decide the order they appear in the site.

    Any suggestion of how can I accomplish that? Any direction would be awesome :)

    Thanks in advance

  3. Hi Devin,

    is there a way to filter optionsframework_tabs, to make it unordered list or something, or to add custom types to optionsframework_fields?

    I don’t want to make changes directly?

  4. Hi, your plug-in is very useful, however I don’t understand how can I add an option that let me switch between different stylesheets, is there a way?

    Thank you

  5. Hi Devin,

    thanks for your amazing framework! Really useful and loads of fun to play around with.

    I’d just like to clarify the use of this in themes for resale. I know the license is GPL so very flexible legally. What I’d like to know is would you be personally happy for your options code to be used in an otherwise original theme to be sold on a site like themeforest?



    1. It’s not that flexible legally. You are welcome to use it as long as your code is also GPL.

      And yes, go for it! That would make me personally happy. :)

      1. Great, thanks Devin!

        I meant flexible compared to a commercial license, I didn’t really manage to articulate that very well.

        Theme Forest license all wordpress realated php as GPL but theme Javascript and CSS are a commercial license. Is this okay or would all need to be GPL?



      1. In Typography there is a text: Some sample text in your style. I can see the changes in face, style and color but not the size.

  6. Dear Devin,

    Tim here, I have come across a plugin that disables the wp theming options framework.

    The plugin is called Coffee Admin Theme.
    It takes all the default values and strips them out and replaces them all with the letter “a”

    And none of the options work.
    Might be something you may want to look into.

    1. I think you must have some other plugin issue going on. Coffee Admin Theme plugin saves its options in the dashtheme_theme option. I didn’t have any issues when I activated it (at least besides all the debug notices).

      1. I deactivated the plugins one by one and no other plugin caused any errors to the options frame work so I could only deduct that it was the above Coffee Admin Theme,

        could there have been something I missed.

  7. Hey Devin,

    I’m trying to get my theme working with wp customizer. I made layouts option using radio/image option picker, and everything’s ok in theme options. Then I added code for layouts to appear in customizer, everything’s good there too, except options are not saving.

    This is the part where option should be updated in customizer:

    ‘settings’ => ‘themename_in_db[site_layout]’,

    Is this possible with of?

    Thank you very much anyway!

    1. Haven’t had a chance to look at it yet. But if is just updating the option, that would be fine. The theme option name is generally set in optionsframework_option_name of options.php. So, it would just be ‘settings’ => your_theme_option_name[‘your_option’]

      1. I found the problem. Looks like options framework is overwriting what’s in theme customizer. Here’s what’s happening:

        I added code for the “example_text_mini” to appear in theme customizer.
        Everything’s ok, you can see “example_text_mini” text in customizer. I type over that text (it’s type text), and it get’s overwritten in preview. Ok.

        When I hit save, it loads the old “example_text_mini” value.

        So, I installed some other theme (doesn’t have theme options), to test things out.
        Then, I added again the same code for customizer to load options from my theme based on options framework. It loads “example_text_mini” option to customizer, and I can change it, save it and everything’s fine.

        But I can’t make it work with my theme. Any ideas?

        Here’s the code I used, just change the “themename_in_db” with your option table name and it will work.

      2. I’ve been working with the theme customizer myself and its been working fine. I’ll post a code tutorial on this soon.

        Your code looked okay. Perhaps you have both the theme customizer open and the theme options page open in the dashboard? If so, you’d need to refresh options panel in the dashboard after making changes on the front end, so that you don’t rewrite them.

      3. Forgot to mention, if it will make you faster to understand – value from theme customizer get’s replaced with option std from options.php in db.

      4. Hey Devin,

        you might tested just changing options values only in the customizer? That works for me too, even if I click save there, it get’s “saved”, but only there, not in theme options.

        I don’t have theme options and customizer opened at the same time, I tested all combinations – with both opened, customizer opened, then saved, went to theme options and I see std value there. And when I get back to customizer, std is there, like in theme options. I hope you understand me.

  8. In Typography there is a text: Some sample text in your style. I can see the changes in face, style and color but not the size. Thanks.

  9. Hi, Devin!

    I’m just fiddling around with your framework and I love it.
    I need a options page for a theme I made for a client. Using the framework it’s a piece of cake.

    I had a little difficulty understanding the meaning of the “plugin version” and the “theme version” and so I did a bit of googling and found this article by Dave Clements.

    In the comments there is a discussion about the Settings API and how the Options Framework handles it.
    Unfortunately I don’t quite understand the point, I’m not an expert in coding.

    You answered the question whether the code is using the API somewhere above:
    “Partially. Fields aren’t outputted in the standard Settings API way (tables), but otherwise yes.”

    What does this mean? Are there any pitfalls concerning further WP-versions?
    I’m just trying to get a feeling for it.

    1. Did you read the “When to Use Theme Version vs. Plugin Version” section in this post?

      Basically, plugin version requires the plugin. Theme version doesn’t, as you put the files in the theme directly.

  10. I did and meanwhile I got it. :-)
    I think the hard thing is to understand that the theme is just a demonstration. It’s confusing because I would expect to see some basic theme with the options inside.

  11. I’m a theme developer and i use options framework on all of my themes and today on wp 3.4 i turned on the wp_debug mode and found a deprecated code in options framework so i decided to visit this website once again to download the latest version and i was so happy to find out that a new feature called text editor was included in the options framework.

    I love your work men! i was thinking of donating later a few bucks to support this project so it will be developed further for others to download for free.


  12. Also Found an Error when saving the values, it says at line 283 no defined function

    $options =& _optionsframework_options();

    it had an underscore and i remove it and it worked. please update your file.

  13. Great options panel! Thanks for your work on this.

    Quick issue I’m dealing with: I have gotten everything setup, but when I try to save the options, I get a blank white screen. I’ve gone through the options.php file carefully and don’t see anything that could be causing this issue.

    Any thoughts on what might be causing this?

    1. A couple people have mentioned there might be a bug with the latest version on GitHub. I’ll look into it this evening. You can always set WP_DEBUG to TRUE if you want to see the error that is being generated.

      1. Thanks for your prompt reply. I removed the underscore (as Jonathan noted) and it works perfectly. Just downloaded from Github yesterday, in case you’re wondering about the source.

  14. Is there a stylesheet available that will move the tabs in the admin panel to the side vs. on the top of the page? (ala woo)

    Working on building a responsive admin stylesheet as WP backshelved it for now and I am finding that on smaller devices there just isn’t enough room on the top for more than 3-4 tabs.

    Been using Lee Masons NHP framework with fully utilizes the WP settings api. Am I right to guess that the options framework also uses the settings api and stores all values in the standard WP table?

    *should I ever change the framework, I don’t want to have to pull my data from a sep non WP table.

  15. Is there a way to accept JavaScript in textarea?

    I have analytics textarea in my theme and when I insert the code, the script tags are stripped away.

    Great work on the framework, thank you very much!

  16. Couldn’t find any info on this:
    1. Is there a ‘repeater’ field type, ala ACF repeating fields?
    – I need to be able to ‘replicate’ a single or group of fields by clicking an ‘add new’ button.
    2. Is there drag n drop ability coming soon?
    – saw the 3 month old ticket on git where smof uses drag n drop to be able to ‘order’ fields on a layout type setup.

    1. No repeater fields. That is a difficult one as all the options are read directly from options.php rather than a database.

      Drag and drop fields are not high on the priority list. Extensible options and inline uploader are much higher.

      However, extensible options might be the path forward for drag and drop.

      1. Devin, I like your idea of a generic plugin that can export/import ANY theme option. In the weeks since you posted that comment, have you become aware of anyone developing such a plugin that works with the Options Framework? I’ve created such a robust theme options panel using the framework that I’ve concluded I probably need a way to save the options to a backup file and restore them if necessary.

      2. Hi Devin,

        Seems like a repeater field wouldn’t be *too* difficult, could you just add the options using javascript and put “[]” in the field names?

      3. It’s more difficult than you’re thinking. Yes, you could create options with javascript to save them, but how would you output them out the next time the panel is loaded? You could store all your entire option configuration in the database rather than just the option values themselves, but then you need to completely restructure how the plugin works so that it pulls from the database rather than options.php. Make sense?

    1. It’s saved in the options table of the WordPress database. If you have a plugin that backs up your data it will backup your theme settings as well.

  17. When I install my theme in a new and clear installation, the theme looks ugly. It doesn’t load the default options from the options framework until I save the options. What am I missing?

    1. Whoever developed your theme probably didn’t provide defaults in their of_get_option calls, so the theme won’t properly work until defaults from the options array are saved into the database.

      1. Hi Devin,

        Regarding my other recent comment, it seems to be related to this previous issue as posted by @Javier. Your reply was as follows:

        “Whoever developed your theme probably didn’t provide defaults in their of_get_option calls, so the theme won’t properly work until defaults from the options array are saved into the database.”

        This idea of having defaults defined in two places really doesn’t seem practical to me. The defaults are defined in options.php and I really shouldn’t have to define them in the individual template PHP files as well – this would make updating and maintaining the theme a real pain.

        The logical solution would be for the default options values in options.php to be saved to the database when the theme is initialised / used for the first time. Can you please advise how I might do this?


      2. Okay, I see your follow- up here. There is a function to save the options when the theme is first loaded, but it doesn’t work consistently (as you’ve noticed). And, I’ve actually been trying to strip out that code based on Otto’s recommendation:

        If you do want to try and get this working, trace down the function “optionsframework_setdefaults” in:

      3. Hi Devin,

        Thanks for responding so quickly. I’ll definitely give optionsframework_setdefaults() a try.

        I’m not convinced about what Otto says – the brief quote offers no justification for his statement. All the settings are going to be stored in the database the instant the user makes even the the tiniest edit anyway, so I see no harm at all in preempting that and ensuring the settings are stored & retrieved in a consistent way, with only one file to store the defaults instead of having to set each default twice, in a massive number of different locations in a huge number of different template files, as well as in options.php. I think that’s unsustainable development, but of course that’s my opinion.

  18. Hey! just want to say that I really like your Options Framework. I translated to french if you’re interested. I also changed the “text domain” in two or three spots where it wasn’t set to “options_framework_theme”.

  19. Nice improvement btw,

    I have question for you.
    Have you any idea to make “ajax save”? So, whenever we hit the save button, it will not refresh the whole page. Just like wootheme option panel.
    thank you.

    1. I’m trying to use the core Settings API as much as possible. Earlier versions of the framework had an ajax save, but it was stripped out quite a while ago. You’re welcome to use one in your own implementations.

  20. Hi Devin,

    I’m creating a number of themes using options framework built in to the theme. I have a curious thing happening: when I first install the theme, the website looks broken, as if it’s not picking up the theme options. Then I go into the options screen, click ‘save’, reload the website and all of a sudden everything looks OK.

    Any idea where I’m going wrong?


  21. I just spent about 12 hours trying to make an MCE editor in the theme options save to database. So your solution makes me very happy! Plus, now I don’t have to figure out the next 12 things I planned.

    As a UI designer and developer, I rarely find something that makes me this happy. Thanks so very much.

    1. Hi Nauman. I can’t help debug/customize code- but you should be able to have repeatable patterns no problem with the standard options. You just need to have it set to “repeat” by default.

      1. Devin i got that working with same logic as you defined for “Sidebar Position”.

        i have one more question

        you have used in logo

        “class” => “hidden”

        to hide upload and logo width options i copied same code but its not working for me can you please tel me how it works..

  22. Devin,

    How can we translate the output of the theme options with a translation/multi language plugin? I am getting complain that they are not being translated.. do you have any idea bout how to make them translatable? for example like this maybe:

    Let me know!

    1. As long as you set your text domain and translation strings properly, the options labels, etc. should translate fine. I’m not sure what your theme would need to do to be compatible with the WPML plugin.

    2. I was talking about the theme options output not the theme options label. For example if I add a text field in my theme options the output on frontpage cannot be translated with any kind of wpml/qtranslate plugin but the plugins can translate everything else. do you have any suggestion? Am I missing something? I added a code in my comment earlier which is missing can you take a look.

      And Do you have any other payment options to donate other than paypal. I want to donate but I dont have a pypal account. My country is not yet supported. :(


      1. Hi Towfiq,
        I just saw your post and I have the same issue than you with output fields and WPML translations. Did you get to translate this fields? How did you do?

  23. Hello,
    Great work. really useful!
    I’m a beginner and i have a question. I did create my own theme from scratch, and now, i wanted to install/use your framework. I installed it in my theme as shown in the video.
    The thing is, i created the tabs and fields for the theme customization but i didn’t understand how to make it work.
    For example, i created a “field” to change the header background color, but i didn’t understand how to make it work (to apply the change on the theme).
    Do you have a video tuto or an example that could help me understand?
    Thank you

  24. Hi Devin,
    I am a complete newbie at plugin development, and when I have come across this, I got an “aha moment”. Can I use this for options of plugins that I make for WooCommerce?


  25. Hey there – I purchased this package and am loving it so far. One thing I noticed though is that the hidden text inputs that fade toggle are not very dynamic with the jquery. For instance, my theme will have social media icons but not everyone wants to use all icons. So there will be check boxes for the icons they want to use in the options panel. If they check a box the hidden field will appear for them to enter the URL to their profile. Right now if I wanted many different options and corresponding reveal text fields I would have to rewrite your example jquery on click method many times. I figured this wasn’t very good, one simple click method should work fine for all. Here’s what I did:

    1. Added a class ‘reveal-text’ to all toggle checkboxes.

    2. Added a class ‘hidden’ to all corresponding toggle inputs

    3. Coded some jQuery to climb up DOM and target next corresponding hidden field:

    //hidden text
    $('.reveal-hidden input[type="checkbox"]').click(function() {

    if ($('.reveal-hidden input[type="checkbox"]:checked').val() !== undefined) {

    Again, great resources here. Compared to most options panel this one is the most clean and uses Settings API nicely. Hopefully we’ll get a more elegant solution for multiple hidden text toggles but this will do for now!

      1. I extended this solution (from issue #113) so that it can show/ hide several controls (regardless of their types) by checking/ unchecking a single checkbox, as follows:
        1. I added a “parent” attribute to each hidden field, whose value must be the ID of the checkbox:

        $options[] = array(
        'name' => __('Check to Show a Hidden Text Input', 'options_framework_theme'),
        'desc' => __('Click here and see what happens.', 'options_framework_theme'),
        'id' => 'example_showhidden',
        'class' => 'has_hidden_child',
        'type' => 'checkbox');

        $options[] = array(
        'name' => __('Hidden Text Input', 'options_framework_theme'),
        'desc' => __('This option is hidden unless activated by a checkbox click.', 'options_framework_theme'),
        'id' => 'example_text_hidden',
        'std' => 'Hello',
        'class' => 'hidden',
        'parent' => 'example_showhidden',
        'type' => 'text');
        $options[] = array(
        'name' => __('Input Radio (one)', 'options_framework_theme'),
        'desc' => __('Radio select with default options "one".', 'options_framework_theme'),
        'id' => 'example_radio',
        'std' => 'one',
        'parent' => 'example_showhidden',
        'type' => 'radio',
        'options' => $test_array);

        2. I added the parent name as a class, in the generated markup (the function optionsframework_fields() in class_options_interface.php):

        // Wrap all options
        if ( ( $value['type'] != "heading" ) && ( $value['type'] != "info" ) ) {
        if ( isset( $value['parent'] ) ) {
        $class .= ' ' . $value['parent'];

        3. I modified the options_custom.js as follows:

        // checkboxes with several hidden inputs

        if ( $(this).is(":checked")) {

        $(this).change(function() {


  26. Hi, looking for some advice please – I’m using a theme (bought on Themeforest) that contains your Theme Options panels and when I click ‘Save settings’ after changing things they are not saved and just default back to the original setting? The theme author is completely stumped and doesn’t know why it is doing this…dont suppose you might have any ideas as to why the theme options might not be saving?

    Any help you can give me would be much appreciated!! :)

    1. You should tell the theme author to get in touch with me.

      Did you change the name of the theme, the theme folder name, or make any other customizations?

      1. Thanks for your reply!

        The author/thread where they discuss your options framework is here – – I’ll post up a new reply saying that you’ve asked that they get in touch.

        I haven’t changed the theme name nor make any customizations at all…I was scared that would break things so I just uploaded it as is to test it and it didn’t work.

        I’ve also been in touch with my server company (the theme authors thought it may be a permissions issue, but everything there seemed ok there) and they asked if any theme elements used http loopbacks…does your theme options framework use them?

        Once again, thanks for your help – I’m trying to build a site for a client and if I can’t get this theme to work I’m a bit stuffed! :(

    2. Hi Closer,

      I’m also using Options Framework for my themes and some of my users also having this issue, It can be fixed by re-install the WordPress installation with manual install method.

      I don’t know what exactly the problem but for some case the theme options won’t save the options because you’re using script installer such as fantastico to install the WordPress, it’s no problem if you’re using SimpleScript.


  27. Hi,

    great framework. I have a question, I don’t figure out how to get the meta (alt, description,etc) from an image upload with the “uploader”, you don’t save the ID but the URL of the image. Do you have an idea?

    Thanks, continue your great work.

  28. Hi! I’ve been playing around for some time with your framework, it works great! But today i’m trying to implement a “multiselect” solution over the select list. I’ve got the multi select (from jquery ui) to work but when I try to save the values nothing happens (the values aren’t stored).

    Could you help me out with this, it’s killing me!

    Great work with your plugin, thanks for everything.

  29. Hi Devin, I was hoping I could revisit a feature request. The ability to choose a post as well as a page, or both. You argued last time that the number of posts would mean too many queries on the db.

    This options plugin is awesome for small business websites that use WordPress as a CMS where they still use posts but they have a limited number <50.

    This plugin has a feature whereby you can choose any tag, and in theory there are normally more tags than there are posts.

    For all of us who don't have a large number of posts, and would love a drop-down feature to choose a page, or a post or both would you reconsider this feature, or show us a patch we can use.



  30. Hi, Great framework, thanks for the contribution.
    Any ides why shortcodes e.g. [shordcode] do not work in the theme option fields. Maybe it get sanitized? Maybe it’s just me?



  31. Re: “Display admin menu link only if user has permissions”

    i have a strange situation where i need to do the opposite – restrict access to posts and pages for all users, and only allow access to Options Framework. any easy solutions for this?

    1. I really should spend more time looking for solutions before i post up here. sorry.

      i’ll use this :
      function remove_menus () {
      global $menu;
      $restricted = array(__('Dashboard'), __('Posts'), __('Media'), __('Links'), __('Pages'), __('Tools'), __('Users'), __('Settings'), __('Comments'), __('Plugins'));
      end ($menu);
      while (prev($menu)){
      $value = explode(' ',$menu[key($menu)][0]);
      if(in_array($value[0] != NULL?$value[0]:"" , $restricted)){unset($menu[key($menu)]);}
      add_action('admin_menu', 'remove_menus');

  32. Not so much a question but I’m just curious. When implementing the color option for example. I’ll typically end up having a separate file, eg. styles.php, which will house a function that includes all my CSS rules that use that color option, and then add it through wp_head.

    Is there a better/preferred way of including such css rules that are defined by options?

    1. I think it’s probably always better to enqueue stylesheets, as those can be easily unhooked, minified and combined by plugins, etc.- but I’m not sure how well that all works when the css is actually a PHP file.

      My preferred method is to load it inline in the head. I know that feels a bit messier, but it always works, still allows those styles to be compressed and minified, and saves the user an HTTP request.

  33. Hey Devin,

    Your framework is really awesome! I can’t wait to start hacking away at it.

    My only two wishlist items (and one, you already addressed) are image/content sliders and shortcodes. I saw, shotcodes aren’t enabled, but are there any plans to add this functionality?

    Image/Content sliders would be pretty cool for home pages and gallery or portfolio pages.

    Either way, just wanted to say great work and thanks for making this available at such a reasonable price!


      1. Hi there,
        i’m wondering how this is possible as well. Ive tried adding the php to an editor options panel, however I don’t think it will echo on the front end.

        I’m assuming because WordPress doesn’t allow php to be placed into editor’s. Would love more information, or a workaround on this.

        Thank you!

  34. Hi there,

    Everything is working fine! Well, almost everything. If I use ‘editor’ the input output empty. No editor, no textarea, anything. ¿Any suggestion please?

    $options[] = array( "name" => __('Test editor',THEMENAME),
    "desc" => __('Testing editor',THEMENAME),
    "id" => "tyni_mce_field",
    "std" => __('Smaple text...', THEMENAME),
    "type" => "editor");

Leave a Reply

Your email address will not be published. Required fields are marked *