theme-configurator: add WordPress theme options pages

November 26, 2011

Hi guys, this is about a little WordPress plugin I’ve recently released.
theme-configurator, the easiest and most elegant way to add customized theme options pages to your WordPress theme–no coding required.

Download and official plugin directory at WordPress:

Development and bug tracking:

Video Tutorial

This video tutorial I am go through the simple steps of setting it up.

[embedded youtube video here]

You can also read the following transcript here.


Hi, my name is Igor Prochazka and I’m the author of theme-configurator, the easiest and most elegant way to add customized options pages to your WordPress theme — without any coding. In this tutorial I’ll show you how to use this plugin.

Let’s go and take an existing theme and add some theme option pages to it. As an example I’ll start with a theme called “Basal” by a guy called Ryan McNair. I’ve got it from WordPress’es pool of free themes. As you see it is pretty minimal.

Obviously the user will want to tweak its appearance. theme-configurator’s first version focusses on three major topics: colors, dimensions and text. It will add an option page for each of them. I’ve already downloaded and installed the plugin. You can get it directly from your WordPress admin panel. I activate the plugin. And we now see the three additional items in the Appearance menu.

This is the colors page. You can use this fancy color wheel in order to change the color scheme.

On the dimensions screen simply drag sliders in order to modify dimensions in your theme. These might be values for content width, font size and so on.

Finally the text page offers a way to modify certain text phrases in your theme.

Now, the current set of colors, dimensions and text phrases is the one that comes pre-installed with the plugin. It’s just an example and, of course, we’ll need to adapt this selection to our theme. With theme-configurator there’s no programming needed for this job, either.
The corrresponding administration page is hidden by default. Go to Settings and check the theme-configurator option and it comes up.

Here it is.

Now you can manage all configurable items. Let’s edit a color, we’ll change it’s name and save it.

We’ll delete a color. Now let’s switch to the dimensions tab. Change the range of valid values editing minimum and maximum. Save.

Move options up and down, and so on. In the “General” section you can choose which of the screens you to be shown.

We’ll come to the “Prefix for WordPress options” field later. When you’re done, don’t forget to save all your changes.

Now this is what theme-configurator does: to take off your shoulders the burden of programming theme options pages by yourself. However, it’s still your job to make use of that user input. theme-configurator does not do any magic to actually change the appearance of your site. Luckiliy WordPress makes that a cakewalk, even for non-hackers. I’ll give you some examples.

Our theme uses some fixed phrases that are hardwired directly in the theme. Let’s take the phrase “Categories” as an example. With theme-configurator we want to make this dynamic and configurable. I’ll edit the theme with WordPress’es built-in editor. I’ve already taken a look at the code and found the text phrase here in the “sidebar.php” file. Now we’ll substitute the text with a small PHP snippet that loads the text from WordPress options database table.

<?php echo get_option("basal_categories") ?>

The get_option function is baked into WordPress and it is the standard way of retrieving options. “categories” is the name of our text option. In this case it comes pre-defined with theme-configurator. You’ve also noticed a prefix, here “basal_”. The plugin uses it as a way to prevent its options from clashing with other options that WordPress and other plugins need for their normal operation. By default, the prefix is set to the current theme’s name. If for whatever reason that’s not convenient for you, you can change it on the “general” tab on the theme-configurator’s administration page.

Let’s change “Categories” to Spanish for fun: “Categorías”. It becomes clear that this plugin can also be used as an alternative way of translating your themes to different languages. Let’s see if it worked. There you go.

Now let’s do the same thing for the theme’s background color as another example. The logical step would be to edit the CSS stylesheet directly. However, on most WordPress set-ups files with the .css extension don’t accept PHP code. That’s why we go to “header.php” instead.

Within the HTML head section we’ll introduce a new style tag pair. A here we use the get_option function again.

  body {
    background-color: <?php echo get_option("basal_background") ?>;

That’s it. To check our settings I will change the background color to pink. Now let’s see if it works. Beautiful!

So if you just need a way of adding some flexibility to your own blog or your client’s one, you are done at this point. If you are a theme developer and you want to ship your theme together with the theme-configurator plugin, you’ll need to save your settings on disk.

The plugin does that for you. Reveal the “Storage” settings on your theme-configurator administration page.

It tells you what state the current configuration is in. Let’s press the “Update theme’s settings” button. Behind the scenes, this saves your settings in two files: thcfg-settings.json and thcfg-structure.json that reside in your theme’s root directory.

Now you are ready to go. Your users can now deploy your modified theme and, with theme-configurator installed and activated, they will be able to tweak colors, dimensions and text phrases by themselves.

Ok, that’s about it. Give it a shot. I’m waiting for your comments and suggestions. Thank you for watching this tutorial and my apologies for my German accent. A transcription of this video will be available at this URL. (

See you later!



  1. November 26, 2011

    Its not working on localhost with default twenty-eleven or newly download theme from wp repo.

    any further ideas pls?

  2. November 26, 2011

    Thanks for the feedback. Could you be more specific? Some error appears? New menu items don’t show up? Screens inaccessible? Please also tell me your WP version.

  3. November 26, 2011

    Thanks for quick feedback. Well, let me try again and see how it goes… :)

    No errors though on wp 3.2.1

  4. August 28, 2012

    Wow! I hope the plugin is as good as the first video. Taken off to hear the rest. Very nice. Great photography! Good to see live concert!

  5. November 1, 2013

    Haven’t seen an update for this in a while. Wonder if you would consider merging with Redux like NHP just did?

  6. June 19, 2017

    Hi, very nice article.

Please, leave a comment here