Creating Custom Settings For Your Theme in Customize

In Version 2.1 we added the ability to manage your theme’s custom settings in a much easier way, using a json file, much like do to configure your theme initially. If the case you want to add some custom settings to your theme in the Customize view of the WordPress admin, you can now just navigate to config/themeCustomizeSettings.json and edit the JSON object. By default, the file looks like this:

{
  "theme_name": "wp-rig",
  "settings_id": "wp-rig_theme",
  "sections": [
    {
      "id": "global",
      "title": "WP Rig Settings",
      "priority": 30
    }
  ],
  "settings": [
    {
      "id": "ga_id",
      "label": "Google Analytics ID",
      "section": "global",
      "refresh": false
    }
  ]
}

You can add as many sections and settings into this object as you like. Each setting must correlate to a section defined in the “sections” array prop. There are more details below about acceptable input for this

The structure of the JSON object attempts to follow the args you see being passed in core WordPress as much as possible, however, some liberties were taken to improve simplicity

Once you have edited the JSON object, you should be able to just save and refresh the customizer in the WordPress admin to see your new settings in there. Retrieving the values of these settings throughout your code is as easy as using the get_theme_mod() function while passing it the ID of your setting.

Array structure details

  • theme_name: The name of your theme (without spaces – like an ID)
  • settings_id: Unique ID for these settings (for storage in the DB)(I might make this optional in the future)
  • sections: Define each new section to be added to the customizer. We lumped in id for simplicity. ‘title’ allows for localization
  • settings: Each setting is it’s own array in this array of settings. We tried to combine the args for settings and controls as much as possible to keep this as simple as possible. For the most part, all args from this WP Codex function apply. Also All control args can be passed in, view Codex docs for controls for more details on how those work. We changed ‘transport’ to ‘refresh’ because it makes more sense
    • type: (optional) All base core types are currently supported. Type is optional, if not included, a basic text field is assumed. The following more complex types are also supported:
      • Basic Types include: ‘text’, ‘checkbox’, ‘textarea’, ‘radio’, ‘select’, and ‘dropdown-pages’. Additional input types such as ’email’, ‘url’, ‘number’, ‘hidden’, and ‘date’ are supported implicitly.
      • color – Color Picker
      • date – Data/Time Picker
      • media – Image/Attachment Selection