Theme options reference

Theme options are settings your theme offers in the Layout Editor, so that the people who publish with it can adjust it without changing the theme. You declare them in the options list of theme.json, and templates read the value chosen for the layout as theme.options.<key>.

{
    "key": "accent",
    "type": "color",
    "label": "Accent color",
    "description": "Links, buttons and the portal banner.",
    "default": "#3a46e8"
}

Field	Required	Description
`key`	Yes	The name templates use. An option without a key is ignored.
`type`	No	The kind of value, which decides the field in the Layout Editor. See the types below. A missing or unknown type gives a text field.
`label`	No	The option's name in the Layout Editor. Without one, the key is shown.
`description`	No	Help text shown under the field, up to 500 characters.
`default`	No	The value used until someone changes it. Give every option a default, so that the theme works before anyone sets it.
`values`	For `select`	The choices.

Types

Type	Also written as	In the Layout Editor	Value in templates
`color`		A color picker	A string
`text`	`string`, `url`	A text field	A string
`select`	`choice`, `enum`	A list of choices	A string
`toggle`	`bool`, `boolean`	Enable or Disable	`true` or `false`
`number`	`int`, `integer`, `float`	A text field, checked for a number when the layout is saved	A number
`image`		Upload image	The image's file name

color: The value must be a hex color with 3, 4, 6 or 8 digits, such as #3a46e8, or a CSS color name, such as rebeccapurple or transparent. Values such as rgb(…) and hsl(…) are not accepted. Use a default of "" to let the option be left empty, and test for it in the template.

<style>:root { --accent: {{ theme.options.accent }}; }</style>

text: Up to 2,000 characters.

select: List the choices in values, either as objects with a value and a label, or as plain strings that are both:

{
    "key": "hero-contrast",
    "type": "select",
    "label": "Portal banner text and logo",
    "default": "auto",
    "values": [
        { "value": "auto",  "label": "Automatic (from the background)" },
        { "value": "light", "label": "Light" },
        { "value": "dark",  "label": "Dark" }
    ]
}

"values": ["auto", "light", "dark"]

A select without any values is shown as a text field.

toggle:

{% if theme.options.sidebar %}
    <nav class="sidebar">…</nav>
{% endif %}

number: Any finite number, such as 68 or 1.5.

image: The person setting the option uploads an image, and Paligo publishes it with the theme's assets. Use asset() to link to it:

{% if theme.options['hero-image'] %}
    <div class="hero" style="background-image: url('{{ asset(theme.options['hero-image']) }}')"></div>
{% endif %}

Reading options in templates

Use a dot for a simple key, and brackets for a key with a hyphen in it:

{{ theme.options.accent }}
{{ theme.options['hero-image'] }}

The Layout Editor checks values when the layout is saved. If a stored value doesn't suit the option's type, such as after you change an option from text to toggle, it is ignored when publishing and the default is used.

Theme options reference

Types

Reading options in templates

Search results