Canopy Block Settings

Settings define the fields content editors fill in for each Canopy Block. You declare them in the settings array of a block template's config section, and their values are available in the template section through the settings variable.

All setting types share these attributes:

Tabs and groups

Blocks with many settings can organize them so editors are not shown everything at once. Both attributes are optional and only affect the editing form — they change nothing about how you access values in the template section.

Give settings a tab to split the form into tabs. Tabs appear in the order they are first used, and any settings without a tab are gathered under a General tab. The form only shows tabs when at least one setting declares one.

Give consecutive settings a group to place them under a labelled divider. Groups are open by default, and editors can collapse them.

{
    "title": "Hero",
    "name": "hero",
    "settings": [
        { "name": "title", "type": "text", "tab": "Content" },
        { "name": "description", "type": "textarea", "tab": "Content" },
        { "name": "background", "type": "color", "tab": "Style", "group": "Colors" },
        { "name": "text_color", "type": "color", "tab": "Style", "group": "Colors" },
        { "name": "custom_class", "type": "text", "tab": "Style", "group": "Advanced" }
    ]
}

This config gives the block a Content tab with two fields, and a Style tab where the color settings sit under a Colors group and the class setting under an Advanced group.

Text

type: text

A single line of plain text. The value is a String, with "New text" as the built-in default.

<p>{{ settings.subtitle }}</p>

Textarea

type: textarea

Multiple lines of plain text. The value is a String, empty by default.

Richtext

type: richtext

Formatted text edited with a rich text editor. The value is an HTML String, so output it with the raw filter:

<div class="prose">{{ settings.body|raw }}</div>

Select

type: select

A dropdown of predefined options. The value is the selected option's value as a String.

{
    "name": "alignment",
    "type": "select",
    "options": [
        { "value": "left", "label": "Left" },
        { "value": "center", "label": "Center" },
        { "value": "right", "label": "Right" }
    ],
    "default": "center"
}

Radio

type: radio

A set of radio buttons. Works exactly like Select, with the same options attribute, but shows every option at once in the editor.

Checkbox

type: checkbox

A single on or off toggle. The value is a Boolean, false by default.

{% if settings.show_title %}
  <h2>{{ settings.title }}</h2>
{% endif %}

File

type: file

A file picked from the site's assets. The value is an object describing the file.

{% if settings.brochure.path %}
  <a href="{{ settings.brochure.path }}" download>{{ settings.brochure.name }}</a>
{% endif %}

URL

type: url

A link with editable text and target. The value is an object.

<a href="{{ settings.cta.url }}" target="{{ settings.cta.target }}">{{ settings.cta.text }}</a>

Date

type: date

A date picker. The value is a formatted date String.

Color

type: color

A color picker. The value is a hex color String, #000000 by default.

<section style="background-color: {{ settings.background }}">...</section>

Heading

type: heading

A heading with editable text and an editable HTML element. The value is an object.

<{{ settings.heading.element }}>{{ settings.heading.value }}</{{ settings.heading.element }}>

Number

type: number

A numeric input. The value is a Number.

List

type: list

A repeatable list of text items. The value is an Array of Strings, empty by default.

<ul>
  {% for item in settings.features %}
    <li>{{ item }}</li>
  {% endfor %}
</ul>

Media Sources

type: media-sources

A list of media files for HTML5 audio and video elements. The value is an Array of objects, each with a url and a type (the MIME type).

<video controls>
  {% for source in settings.video_sources %}
    <source src="{{ source.url }}" type="{{ source.type }}" />
  {% endfor %}
</video>