WordPress.org recently announced that all new themes will be required to use the Customize API as an interface for theme options.

See New Theme Settings Customizer Guideline

All new themes must immediately adhere to the requirement, and all existing themes will be required to convert on the first update after October 21st (6 months from now).

Theme Customizer is a great interface and I totally support the decision. It is much simpler then developing a custom panel system as was done in the past. Once you have been through setting up theme options using the Customize interface, you will feel much more in control of your options system.

The Panache WordPress Theme, recently approved at WordPress.org, uses the Customize System to create a multi-panel multi-section system in the Customize interface. I have taken that system and adapted it so you can use to set up your options for your theme.


  • one panel/one section to multi panel/multi section
  • data sanitization
  • use theme_mods table or separate table or both
  • controls offered
    • text
    • textarea
    • image upload
    • file upload
    • media upload
    • select list
    • radio list
    • checkbox
    • range slider
    • category list
    • tag list
    • color picker
  • All options collected in a single array variable for use throughout the theme
  • The option system also allows you to attach an html script to the first panel, ideal when offering theme links and a PayPal button

Options saved to the theme_mods table will allow you to create different looks for your site, as they will be setup for the theme and will also need to be setup in each child theme. Options saved to the separate options table will carry through to the child themes as well.

The system does not include any code for the Customize Live preview panel. All options will load on page refresh. However you can set up your options using ‘transport’=>’postMessage’ and then provide the code to make the CSS changes live. See Codex Customize API

As a developer, I strongly suggest you learn how to setup a customize system from scratch. It will help you understand the code in this download. If you only have a few options then don’t use this setup system, do it yourself from scratch. This setup system will really come in handy if you are developing a theme with a lot of options.


Set up – New options system

  • Download the file and unzip it.
  • Put the kha-customizer.php file in a folder within your theme folder, this is usually /themes/YourTheme/includes/ or something like that
  • Add the following to the top of your functions file
    and replace themeslug with yourthemeslug 🙂
  • Do a search and replace themeslug with yourthemeslug 🙂
    • If your theme slug is hyphenated, such as your-themeslug, make sure all text domains are your-themeslug, and all function and variable prefixes are your_themeslug
  • Setup your panels and sections
  • Setup your options

Default Settings

I would advise against saving any options at this time because you will be changing setup options.

KA WordPress Customize Setup is initially setup with three panels to get you started. If you went into “Appearance=>Customize” at this time you would see the following :


Add HTML block to Customize Panel

This function allows you to add a block of HTML script to the top of the first panel you create. It allows you as a developer to add the theme links and even a PayPal button if you want.

  • make sure that panel1 in the add_action() is replaced with the id/name of your first panel
  • eplace themeslug with yourthemeslug
  • modify the links to the links you want
  • add your PayPal link if you want

Set Up your Panels

The first panel is shown below, with two sections

  • replace themeslug with yourthemeslug
  • Fill in the panel and section information as shown by the comments
  • Add sections and panels
  • delete any of the panel/section code that you do not require

Set up your options

Example code for the first select option is shown below.

  • replace themeslug with yourthemeslug
  • Fill out the option info as per the comments
  • repeat for the options you want
  • Delete any options you do not want

Users who are updating existing options

Be very careful wen you are switching to the Customize API with an existing set of options.
  • Make sure the save option corresponds to the table you are using
    • ‘save’=>’theme_mods’ to use the theme_mods table
    • ‘save’=>’save’=>’option’ to use the separate table
  • Make sure your options have exactly the same name or you will not be able to access them
  • If using a separate table make sure you are using exactly the table name you are saving your existing options under
    • search and replace ‘themeslug_customize_options’ with your table name
  • Deactivate your settings API by commenting out (initially) the file loads for your options
  • Make sure you have gone through your theme and are using your options with the appropriate setup function
  • test…..test…..test
  • After successful testing delete all the replaced options setup files and references
All comments and suggestions welcome 🙂