When would it be appropriate to use the settings API, and when would it be better to use the theme customizer?

Having Googled around all morning, I haven't been able to find any well considered and recent guidance on this matter. While it's still early to say, I feel that the theme customizer is a suggestive first step towards bringing in more Squarespace-like editing features. Does anyone know of any plans to sunset the settings API in favour of the theme customizer? Should we all slowly be moving towards it, or would we be better off sticking to the settings API? Can they live side-by-side, and if so, where would the division of responsibilities lay?

2 Answers 2


The premise of the question is flawed. The Customizer API is not an options API, but rather an options preview API. The Customizer API relies on either the Settings API or the Theme Mods API to register controls for existing settings added via either of the two APIs.

The Customizer does not - and cannot - define/register new settings that have not already been registered via either the Settings API or the Theme Mods API. Said a different way: The Customizer API is not an API to add settings directly to or to retrieve settings directly from the database; rather, the Customizer API uses either the Settings API or the Theme Mods API to save settings to, or to retrieve settings from, the database.

Thus, the Customizer API isn't an alternative to one of the existing options APIs; rather, it is an alternative for a settings page. The Customizer doesn't care whether a setting is registered via the Settings API or the Theme Mods API, and such settings can be mixed and matched in the Customzer. In fact, in most cases, such settings are mixed and matched: custom header and custom background are Theme Mods, and Site Title and Description are Settings API.

To understand exactly how settings and controls are registered via the Customizer API, I recommend reading Otto's excellent tutorials:

So, the question isn't either/or with respect to the specified APIs. Appropriate either/or questions would be:

  • Use either the Settings API or the Theme Mods API to register existing settings to preview via the Customizer API
  • Use either the Customizer API or a custom Theme settings page to allow the user to configure Theme options.
  • Thanks Chip. I still don't 100% follow you, but you've given me enough to go and look into the issue some more. I think my confusion stems from the overlap in functionality and the similarity in the names. Is there page that clearly documents the use cases (in a more abstracted way) of the different APIs? I haven't had much luck looking through the codex; it just focuses on the nuts and bolts of applying the API.
    – Dre
    Commented May 2, 2013 at 12:00
  • I've added more, to try to explain a bit more in-depth. See also, especially, the links to Otto's Customizer tutorials; I think they will help clarify things. Commented May 2, 2013 at 12:19
  • You sir are a gentleman.
    – Dre
    Commented May 2, 2013 at 13:06

As simple as things can sometimes be: The Settings API is not the Theme Customizer. Both are different things for different tasks.

Settings API

You're either writing a plugin or have a theme that doesn't have options that won't need any visual feedback? Go with this option.

Theme Customizer

You need to have options that have a visual impact that the user should be able to see? Go with this option.

  • This was my initial conclusion. However, there is a great deal of functional overlap between the two, which is what lead to the original question(s). Additionally, the idea of splitting up theme options into two locations depending on whether they are visual or not strikes me as problematic from a UX point of view. That's not to say that I disagree with you; I'm just soliciting opinions at this stage. The whole topic itself is somewhat murky. Perhaps some well defined guidance 'from on high' would be beneficial. Thanks for your input!
    – Dre
    Commented May 1, 2013 at 10:33
  • @Dre Guess you misread it a bit: If you got even one single option that needs visual feedback, go with the ThemeCustomizer. So the rule of thumb is: Theme -> Theme Customizer | Plugin -> Settings API.
    – kaiser
    Commented May 1, 2013 at 10:59
  • As a general rule, all Theme-defined options should have a presentational impact. :) That said: the Customization API requires either the Settings API or the Theme Mods API in order to exist. The Customization API isn't an alternative for one of those two APIs, but rather an alternative for a custom Theme settings page. Commented May 1, 2013 at 14:26
  • Do you guys have any resposiveness issues with the customizer? It seems quite temperamental for me in both 3.5.1 and even more so in 3.6(trunk). I find the heading and close/save buttons often just don't respond properly to clicks and having to sometimes click them several times(and more so in trunk). This is in both FF and Chrome.
    – t31os
    Commented May 1, 2013 at 15:18
  • @t31os Had this problem before, but without consistency. But haven't tried for quite some time. I'd suggest to console.log() all your actions so you see what's triggered and what's interrupting. JavaScript debugging isn't easy...
    – kaiser
    Commented May 1, 2013 at 15:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.