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.

Help and descriptions

Every setting type accepts two optional strings for guiding editors. Like tabs and groups, they only affect the editing form and change nothing about the value in the template section.

• help is a short hint shown as an info icon tooltip beside the field label.
• description is muted helper text rendered underneath the input.

Use help for a quick clarification editors may not need every time, and description for guidance that should always be visible:

{
    "name": "subtitle",
    "type": "text",
    "help": "Shown under the page title.",
    "description": "Keep it under 80 characters so it fits on one line."
}

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>

Collection

type: collection

A collection picked from the site's collections. Use it when a block renders whatever a collection holds, and the editor decides which collection feeds it, such as a block that shows the latest items from any collection they choose. The editor sees a dropdown of the site's collections.

Collection settings use only the base attributes. default may be a collection handle String, and placeholder sets the dropdown's placeholder text.

The value is null while no collection is selected, or when the selected collection has been deleted. Otherwise it is an object:

Each entry in entries exposes its field values under their field names, such as entry.title or entry.image, along with id, created_at, and updated_at.

{
    "name": "source",
    "type": "collection",
    "label": "Collection",
    "help": "All entries of the chosen collection are rendered."
}

Entry

type: entry

One or more entries hand-picked from a collection. Use it when the editor chooses specific content rather than a whole collection: a featured item, a set of related items, or a hand-picked gallery.

display_field only changes the labels in the editor's picker. It never affects what the template receives or renders.

Rendering entries

Each entry exposes its field values under their field names, along with id, created_at, and updated_at, just like the entries of a Collection setting.

With multiple off, the value is the picked entry, or null when nothing is picked or the entry or its collection was deleted:

{% if settings.featured %}
  <h3>{{ settings.featured.title }}</h3>
  <img src="{{ settings.featured.image }}" alt="{{ settings.featured.title }}">
{% endif %}

With multiple on, the value is an array of entries in the exact order the editor picked them, so you can rely on that order for layout. Deleted entries are skipped, and the array is empty when nothing is picked:

{% if settings.related|length > 0 %}
  {% for item in settings.related %}
    {{ item.title }}
  {% endfor %}
{% endif %}

Common configurations

Lock the setting to one collection, and label entries by a specific field while picking:

{
    "name": "featured",
    "type": "entry",
    "label": "Featured product",
    "collection": "products",
    "display_field": "sku"
}

Pre-select a collection but let the editor switch to another:

{
    "name": "highlight",
    "type": "entry",
    "label": "Highlight",
    "default_collection": "products"
}

Let the editor pick up to four entries:

{
    "name": "related",
    "type": "entry",
    "label": "Related items",
    "collection": "products",
    "multiple": true,
    "max": 4
}