Settings API vs Theme Customizer

by

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

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:

  • How to leverage the Theme Customizer in your own themes
  • Theme Customizer Part Deux: Getting rid of Options pages
  • Making a custom control for the Theme Customizer

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.

Leave a Comment