Section Schema

The {% schema %} tag defines a section’s configuration: settings, blocks, and presets.

{% schema %}
{
  "name": "Featured Collection",
  "tag": "section",
  "class": "featured-collection",
  "settings": [...],
  "blocks": [...],
  "presets": [...]
}
{% endschema %}

Schema Properties

Property	Type	Description
`name`	string	Display name (supports `t:` translation keys)
`tag`	string	HTML wrapper tag (default: `div`, `null` for none)
`class`	string	CSS classes for wrapper
`limit`	number	Max instances per page
`settings`	array	Section-level settings
`blocks`	array	Available block types
`max_blocks`	number	Maximum blocks allowed
`presets`	array	Default configurations
`default`	object	Default values for templates
`locales`	object	Inline translations
`enabled_on`	object	Template restrictions
`disabled_on`	object	Template exclusions

Settings

Settings are inputs that merchants configure in the theme editor.

Basic Structure

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Featured Products",
  "info": "Displayed above the collection"
}

Property	Required	Description
`type`	Yes	Input type
`id`	Yes	Unique identifier
`label`	Yes	Display label
`default`	No	Default value
`info`	No	Help text
`placeholder`	No	Input placeholder

Access in Templates

{{ section.settings.heading }}
{{ block.settings.title }}
{{ settings.color_primary }}

Setting Types

Text Inputs

text

Single-line text input.

{
  "type": "text",
  "id": "button_label",
  "label": "Button label",
  "default": "Shop Now"
}

textarea

Multi-line text input.

{
  "type": "textarea",
  "id": "description",
  "label": "Description",
  "default": "Welcome to our store"
}

richtext

WYSIWYG rich text editor.

{
  "type": "richtext",
  "id": "content",
  "label": "Content"
}

Output includes HTML tags. Use {{ section.settings.content }} directly.

inline_richtext

Single-line rich text (bold, italic, links only).

{
  "type": "inline_richtext",
  "id": "title",
  "label": "Title"
}

html

Raw HTML input.

{
  "type": "html",
  "id": "custom_code",
  "label": "Custom HTML"
}

Selection Inputs

select

Dropdown selection.

{
  "type": "select",
  "id": "image_ratio",
  "label": "Image ratio",
  "options": [
    { "value": "adapt", "label": "Adapt to image" },
    { "value": "portrait", "label": "Portrait (2:3)" },
    { "value": "square", "label": "Square (1:1)" },
    { "value": "landscape", "label": "Landscape (3:2)" }
  ],
  "default": "adapt"
}

radio

Radio button group.

{
  "type": "radio",
  "id": "alignment",
  "label": "Text alignment",
  "options": [
    { "value": "left", "label": "Left" },
    { "value": "center", "label": "Center" },
    { "value": "right", "label": "Right" }
  ],
  "default": "center"
}

checkbox

Boolean toggle.

{
  "type": "checkbox",
  "id": "show_vendor",
  "label": "Show vendor name",
  "default": true
}

Numeric Inputs

range

Slider with min/max values.

{
  "type": "range",
  "id": "products_count",
  "label": "Products to show",
  "min": 2,
  "max": 12,
  "step": 1,
  "unit": "products",
  "default": 4
}

Property	Description
`min`	Minimum value
`max`	Maximum value
`step`	Increment amount
`unit`	Unit label (px, %, etc.)

number

Numeric input field.

{
  "type": "number",
  "id": "columns",
  "label": "Columns",
  "default": 3
}

Color Inputs

color

Color picker with hex output.

{
  "type": "color",
  "id": "background_color",
  "label": "Background color",
  "default": "#ffffff"
}

color_background

Color picker with gradient support.

{
  "type": "color_background",
  "id": "gradient_background",
  "label": "Background"
}

Output can be solid color or CSS gradient.

color_scheme

Theme color scheme selector.

{
  "type": "color_scheme",
  "id": "color_scheme",
  "label": "Color scheme",
  "default": "scheme-1"
}

Font Input

font_picker

Font family selector (Google Fonts).

{
  "type": "font_picker",
  "id": "heading_font",
  "label": "Heading font",
  "default": "helvetica_n4"
}

Access font properties:

{{ settings.heading_font | font_property: 'family' }}
{{ settings.heading_font | font_property: 'weight' }}
{{ settings.heading_font | font_face }}

Media Inputs

image_picker

Image uploader.

{
  "type": "image_picker",
  "id": "image",
  "label": "Image"
}

Access:

{{ section.settings.image | img_url: '400x' }}
{{ section.settings.image.alt }}
{{ section.settings.image.width }}

video

Video file selector.

{
  "type": "video",
  "id": "video",
  "label": "Video"
}

video_url

YouTube/Vimeo URL input.

{
  "type": "video_url",
  "id": "video_url",
  "label": "Video URL",
  "accept": ["youtube", "vimeo"]
}

Resource Inputs

product

Product selector.

{
  "type": "product",
  "id": "featured_product",
  "label": "Featured product"
}

Returns full product object.

product_list

Multiple products selector.

{
  "type": "product_list",
  "id": "products",
  "label": "Products",
  "limit": 8
}

collection

Collection selector.

{
  "type": "collection",
  "id": "collection",
  "label": "Collection"
}

collection_list

Multiple collections selector.

{
  "type": "collection_list",
  "id": "collections",
  "label": "Collections",
  "limit": 6
}

blog

Blog selector.

{
  "type": "blog",
  "id": "blog",
  "label": "Blog"
}

article

Article selector.

{
  "type": "article",
  "id": "article",
  "label": "Article"
}

page

Page selector.

{
  "type": "page",
  "id": "page",
  "label": "Page"
}

link_list

Menu/navigation selector.

{
  "type": "link_list",
  "id": "menu",
  "label": "Menu"
}

Link Input

url

URL input with link picker.

{
  "type": "url",
  "id": "button_link",
  "label": "Button link",
  "default": "/"
}

Informational

Visual separator/heading.

{
  "type": "header",
  "content": "Layout Settings"
}

paragraph

Help text (read-only).

{
  "type": "paragraph",
  "content": "Configure the layout options below."
}

Blocks

Blocks are repeatable content units within a section.

{
  "name": "Slideshow",
  "blocks": [
    {
      "type": "slide",
      "name": "Slide",
      "limit": 5,
      "settings": [
        {
          "type": "image_picker",
          "id": "image",
          "label": "Image"
        },
        {
          "type": "text",
          "id": "heading",
          "label": "Heading"
        }
      ]
    },
    {
      "type": "video_slide",
      "name": "Video Slide",
      "settings": [
        {
          "type": "video_url",
          "id": "video",
          "label": "Video URL"
        }
      ]
    }
  ]
}

Block Properties

Property	Description
`type`	Unique block identifier
`name`	Display name
`limit`	Max instances of this block type
`settings`	Block-level settings

Rendering Blocks

{% for block in section.blocks %}
  <div {{ block.lms_attributes }}>
    {% case block.type %}
      {% when 'slide' %}
        <img src="{{ block.settings.image | img_url: '800x' }}">
        <h2>{{ block.settings.heading }}</h2>
      {% when 'video_slide' %}
        {{ block.settings.video | external_video_tag }}
    {% endcase %}
  </div>
{% endfor %}

App Blocks

Allow third-party apps to inject content:

{
  "blocks": [
    {
      "type": "@app"
    }
  ]
}

Presets

Presets define default configurations that appear in the theme editor’s “Add section” menu.

{
  "presets": [
    {
      "name": "Featured Collection",
      "settings": {
        "collection": "all",
        "products_count": 4
      },
      "blocks": [
        {
          "type": "heading"
        },
        {
          "type": "product_grid"
        }
      ]
    }
  ]
}

Template Restrictions

enabled_on

Limit where section can be used:

{
  "enabled_on": {
    "templates": ["index", "collection"],
    "groups": ["header", "footer"]
  }
}

disabled_on

Exclude from specific templates:

{
  "disabled_on": {
    "templates": ["password"],
    "groups": ["aside"]
  }
}

Translations

Using t: prefix

Reference translation keys:

{
  "type": "text",
  "id": "heading",
  "label": "t:sections.featured.heading.label",
  "default": "t:sections.featured.heading.default"
}

Translations in locales/en.default.schema.json:

{
  "sections": {
    "featured": {
      "heading": {
        "label": "Heading",
        "default": "Featured Products"
      }
    }
  }
}

Inline Translations

{
  "locales": {
    "en": {
      "heading_label": "Heading"
    },
    "fr": {
      "heading_label": "Titre"
    }
  }
}

Complete Example

{% schema %}
{
  "name": "t:sections.featured_collection.name",
  "tag": "section",
  "class": "featured-collection",
  "settings": [
    {
      "type": "header",
      "content": "t:sections.common.header_content"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "t:sections.common.heading",
      "default": "Featured Collection"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "t:sections.featured_collection.collection"
    },
    {
      "type": "range",
      "id": "products_count",
      "label": "t:sections.featured_collection.products_count",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4
    },
    {
      "type": "header",
      "content": "t:sections.common.header_style"
    },
    {
      "type": "select",
      "id": "columns",
      "label": "t:sections.common.columns",
      "options": [
        { "value": "2", "label": "2" },
        { "value": "3", "label": "3" },
        { "value": "4", "label": "4" }
      ],
      "default": "4"
    },
    {
      "type": "color_scheme",
      "id": "color_scheme",
      "label": "t:sections.common.color_scheme",
      "default": "scheme-1"
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "name": "t:sections.common.blocks.heading",
      "limit": 1,
      "settings": [
        {
          "type": "text",
          "id": "text",
          "label": "t:sections.common.heading"
        }
      ]
    },
    {
      "type": "@app"
    }
  ],
  "presets": [
    {
      "name": "t:sections.featured_collection.preset",
      "settings": {
        "products_count": 4
      },
      "blocks": [
        { "type": "heading" }
      ]
    }
  ]
}
{% endschema %}

Template usage:

<section class="featured-collection color-{{ section.settings.color_scheme }}">
  {% for block in section.blocks %}
    {% case block.type %}
      {% when 'heading' %}
        <h2 {{ block.lms_attributes }}>{{ block.settings.text }}</h2>
    {% endcase %}
  {% endfor %}

  {% if section.settings.collection %}
    <div class="grid grid-cols-{{ section.settings.columns }}">
      {% for product in section.settings.collection.products limit: section.settings.products_count %}
        {% render 'product-card', product: product %}
      {% endfor %}
    </div>
  {% endif %}
</section>

Aqua Basics

Theme Schema

Documentation Index

​Section Schema

​Schema Properties

​Settings

​Basic Structure

​Access in Templates

​Setting Types

​Text Inputs

​text

​textarea

​richtext

​inline_richtext

​html

​Selection Inputs

​select

​radio

​checkbox

​Numeric Inputs

​range

​number

​Color Inputs

​color

​color_background

​color_scheme

​Font Input

​font_picker

​Media Inputs

​image_picker

​video

​video_url

​Resource Inputs

​product

​product_list

​collection

​collection_list

​blog

​article

​page

​link_list

​Link Input

​url

​Informational

​header

​paragraph

​Blocks

​Block Properties

​Rendering Blocks

​App Blocks

​Presets

​Template Restrictions

​enabled_on

​disabled_on

​Translations

​Using t: prefix

​Inline Translations

​Complete Example