Settings API vs Theme Customizer

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.

Leave a Comment