Theme settings API

Almost every theme needs configurable options to handle user needs. Publii allows you to create theme-related and post-related options which allows users to customize the theme and posts layout.

Where to find theme settings?

Theme settings are available under "Theme" menu item in the Publii's sidebar. Under this view you will find "Basic settings" and "Custom settings" areas.

The basic settings area is defined by Publii and cannot be changed by theme. The custom settings area is fully configurable by the theme developer. All your custom settings will be grouped into tabs with options.

Theme settings API

Where to find post settings?

Post settings (if available in the theme) are placed as a last tab under custom settings in the Theme settings view. Under this tab called "Post options" user can define global values for the post settings to avoid unnecessary modifications of every posts to achieve a specific configuration.

E.g. if the user wants to disable displaying creation date for all posts, he can do it under "Post options" tab. But if few posts needs to have a creation date, it is possible to enable it in the post editor under "Other options" tab in the post editor sidebar.

Every option in that tab have usually three values:

  • Use global configuration
  • Disabled
  • Enabled

Use of the global configuration is the default setting.

How to create theme settings?

Theme settings can be defined under config.json file under customConfig field.

The theme settings allows you to use the following fields:

How to create post settings?

Post settings can be defined in the same way as theme settings, but should be placed under postConfig field. 

At this moment post settings allows you to use the following fields:

The post settings fields at this moment do not support the group parameter which is used to create tabs for the theme's custom settings.

How looks a structure of the field under config.json file?

All fields uses a common structure of the field definition:

    "name" // name of the field used to retrieve a value of the field
    "label" // label used to easily recognize a field in the Publii's UI
    "group" // field used to group fields (only for the theme settings fields). All fields with the same value will be placed under the same tabs, that value is also a tab label.
    "note" // use this field to add additional informations for the user. It allows you to use the HTML code as a value
    "value" // default value of the field
    "type" // type of the field
    "dependencies" // array of the rules used to specify if the field should be displayed or not
    [other] // other field-related fields - read a specific field documentation to get more details on it

Below there is an example of the field used for lazy load effects in our themes:

      "name": "lazyLoadEffect",
      "label": "Lazy load effects",
      "group": "Additional",
      "note": "This option works only if the 'Media lazy load' option is enabled in the Website Speed tab under Site Settings",
      "value": "fadein",
      "type": "select",
      "options": [
              "label": "Fade in",
              "value": "fadein"
              "label": "None",
              "value": "none"

Above field will be available under theme as:

{{ @config.custom.lazyLoadEffect }}

That field will be displayed under theme settings in the "Additional" tab as a dropdown field with the three options:

  • Fade in
  • Blur up
  • No LQIP

The default value will be "Fade in". Under the field user will see an additional note with link to the external documentation.

That field will be displayed in the UI only if the option lazyLoad will be set to true.

How to access option values of the theme settings in the theme?

Every theme option value is easily accessible through global @config variable. That variable contains the custom field which is an object where the key is the name field used in the definition of the option.

E.g. if you want to access a value of the option which uses as a name headerColor value, you should write in your theme:

{{ @config.custom.headerColor }}

Above code will output value of the headerColor option.

How to access option values of the post settings in the theme?

The post settings options are accessible in two ways:

  • through* syntax which works in the same way as @config.custom.* syntax for the theme option
  • through postViewConfig object in the post item

Warning! The* syntax works only the single post templates. Under pages with post listings you have to use the postViewConfig object.

E.g. to get post option value defined with name headerColor you can use under the post.hbs file (and also under any custom post templates) the following syntax:

{{ }}

If you want to get the same value under posts listing (e.g.: on the frontpage) you should use:

{{ postViewConfig.headerColor }}

Inside the post item context:

{{#each posts}}
    <h2 style="color: {{ postViewConfig.headercolor }};">
        {{ title }}

Above code will display the posts listing with use of the text color specified per post.

How to create post template-related post settings?

It is possible to create post options which will be displayed only if the specific post template is used (if the post templates are available in your theme).

You have to use the postTemplates parameter. It can be defined as a single post template name:

     "name": "displayAuthor",
     "label": "Display author name",
     "value": 1,
     "type": "select",
     "postTemplates": "alternative",
     "options": [
              "label": "Enabled",
              "value": 1
              "label": "Disabled",
              "value": 0

or as multiple post templates names (separated by comma):

"postTemplates": "alternative,test,portfolio", 

if you need to hide a specific post options for the given post templates names - prefix the postTemplates parameter value with exclamaition mark:

"postTemplates": "!alternative,test,portfolio", 

In the above example, the specified post setting won't be displayed for the alternative and portfolio post templates.