Ghost custom theme settings were introduced in Ghost 4.20.0 and have become a standard way to expose safe, self-serve customization options in the Admin UI.

Custom settings overview

Ghost provides five types of custom theme settings:

• select - renders a select input with several options that can be defined ( options and default is required)
• boolean - renders a checkbox toggle (default is required and can be true or false)
• color - renders a color picker (default is required and it has to be a valid hexadecimal string)
• image - renders an image uploader (default is not allowed)
• text - renders a text input (default is optional)

These have to be defined in the package.json file, more specifically under the config key, where you can also find the posts_per_page and image_sizes defined. You have to create a new key custom and define your custom property.

For example:

{
  "config": {
    "custom": {
      "hero_headline": {
        "type": "text",
        "group": "homepage"
      }
    }
  }
}

In the example above the "hero_headline" will be displayed in the admin area as an input field and the site owner can add any text. To use this new property in Handlebars templates you can reference it like this:

{{@custom.hero_headline}}

Theme settings can be grouped, there are 3 categories:

• Site-wide - for settings that apply to all pages
• Homepage - for settings that apply to the homepage
• Post - for settings that apply to posts

For checking the specific value of custom settings you can use the {{#match}} helper. Example, when a specific typography option is selected:

{{#match @custom.typography 'Inter'}}
  ...code for the Inter font...
{{/match}}

Additionally, you can add a custom description using the description property, and you can define the visibility of a setting. To control when settings are visible, include the visibility key on the dependent setting. This key specifies the conditions that must be met for the setting to be displayed.

Guideline and fallback

Most of the setting types require the "default" property, which is helpful in case the settings is not modified at all by the site owner. The one exception is the "text" type, where this is optional, but in such cases, there is a possibility to do it using handlebars. Expanding on the previous example:

<h1 class='hero__title'>
  {{#if @custom.hero_headline}}
    {{@custom.hero_headline}}
  {{else}}
    {{@site.title}}
  {{/if}}
</h1>

Custom settings are intended for simple visual changes and not complex layout settings.

Official guideline for custom settings

Use cases & ideas

Let's see some of the possible use cases for custom theme settings in your Ghost theme:

• secondary_color
  • provide an option for a secondary color for the theme
  • "type": "color"
• default_color_scheme
  • site owner can set the default color scheme
  • "type": "select"
  • "options": ["System", "Light", "Dark"]
• typography
  • provide different font family combinations
  • "type": "select"
• sticky_header
  • option to make the header sticky
  • "type": "boolean"
• post_feed_style
  • provide different style for the post feed
  • "type": "select"
  • "options": ["list", "grid"]
  • "group": "homepage"
• open_external_links_in_new_tab
  • option to add script for opening external links in a new tab
  • "type": "boolean"

And there are much more general or even specific use cases where custom theme settings will be very useful.

In case you face issues like the theme settings reset during theme updates, you can use the GitHub action to deploy your theme, or check this guide on how to keep custom design settings.

Conclusions

Custom theme settings provide a way to make Ghost themes much easier to customize and change. Depending on what kind of settings your theme has, you can make specific changes without the need to touch any code.