Custom theme settings are a powerful tool that allows theme developers to configure custom settings that appear in Ghost Admin — making it easy for site owners to make stylistic choices without needing to edit theme files.
package.json
file at the config.custom
key, and there are five types of custom theme settings available:
select
boolean
color
image
text
package.json
file, custom settings can be accessed in Handlebars templates using the @custom
object.
@custom
object.
"cta_text"
key is displayed to site owners as CTA Text and can be referenced in Handlebars templates using @custom.cta_text
.
snake_case
where each space is represented by an _
.
Changing a setting’s key when releasing a new theme version is a breaking change for site owners who upgrade from an older version. The setting with the old key is removed, losing any value entered by the site owner, and a new setting with the current key is created with its default value.
"group"
property with the value "homepage"
or "post"
.
"type"
— an unknown type causes a theme validation error.
match
helper:
options
is required and must be an array of stringsdefault
is required and must match one of the defined optionsdefault
is required and must be either true
or false
{{#if}}
helper:
default
is required and must be a valid hexadecimal stringdefault
is not allowed{{img_url}}
helper. You can pass in dynamic image sizes, if you would like to output the image in question at a resized resolution based on your theme config.
default
is optionalpackage.json
instead of adding it in the theme code as a fallback. This allows your theme to handle blank strings in the correct way:
{{else}}
statement:
Landing
, Highlight
, Magazine
, Search
, Off
. If that value is Landing
or Search
, then an additional option becomes visible in Ghost Admin that allows the use of the publication’s cover image as the background. Otherwise, the option is hidden. By configuring setting dependencies, users get a better experience by only seeing settings that are relevant.
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. Typically, you’ll specify the name of the parent setting and value it should have for the dependent setting to be visible. You can also use any NQL syntax for this — the same syntax used for filtering with the get
helper.
Example: Header style and background image
In the following example, the use_publication_cover_as_background
is only visible when header_style
is Landing
or Search
. Note that when the visibility condition isn’t met, the dependent setting will render as null
in the theme (i.e., @custom.use_publication_cover_as_background
will be null
).
show_images_in_feed
setting is only visible when post_feed_style
is set to List
.
{{ghost_head}}
and sets up two CSS variables that reference them:
{{body_class}}
, allowing you to optionally fine-tune and make adjustments to any font: