Settings API vs Theme Customizer

The question:

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?

The Solutions:

Below are the methods you can try. The first solution is probably the best. Try others if the first one doesn’t work. Senior developers aren’t just copying/pasting – they read the methods carefully & apply them wisely to each case.

Method 1

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.

Method 2

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.

All methods was sourced from or, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0

Leave a Comment