Build theme schemas

A schema describes the controls and content structure that Fluid exposes in the visual editor. Place valid JSON between {% schema %} and {% endschema %} in a section or standalone block.

{% schema %}
{
  "name": "Featured collection",
  "settings": [],
  "blocks": [],
  "presets": [
    { "name": "Featured collection" }
  ]
}
{% endschema %}

The schema tag does not render HTML. Your Liquid markup reads the values that an editor selects.

Define a section schema

A section schema can use these top-level fields:

Field	Purpose
`name`	Display name in the editor
`tag`	Wrapper element used for the section
`class`	Class added to the wrapper
`settings`	Controls for one section instance
`blocks`	Repeatable child content definitions
`max_blocks`	Maximum combined number of blocks
`presets`	Initial content and picker variants
`enabled_on`	Template types where the section is allowed
`disabled_on`	Template types where the section is excluded

Use either enabled_on or disabled_on to constrain placement:

{
  "name": "Product highlights",
  "enabled_on": {
    "templates": ["product"]
  },
  "settings": [],
  "presets": [
    { "name": "Product highlights" }
  ]
}

Define a setting

Every setting needs a supported type. Every value-producing setting needs a unique, non-empty id within its settings array. Use the ID to read the saved value:

<section style="background: {{ section.settings.background }}">
  <h2>{{ section.settings.heading }}</h2>
</section>

{% schema %}
{
  "name": "Announcement",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Free delivery on orders over $75"
    },
    {
      "type": "color",
      "id": "background",
      "label": "Background",
      "default": "#e7f0ff"
    }
  ],
  "presets": [
    { "name": "Announcement" }
  ]
}
{% endschema %}

Common setting fields include:

Field	Purpose
`type`	Editor control or resource selector
`id`	Stable key used in Liquid and saved data
`label`	Label shown to editors
`default`	Initial value
`options`	Choices for selection controls
`min`, `max`, `step`, `unit`	Numeric control constraints
`content`	Text displayed by a `header` setting
`visible_if`	Conditions that control editor visibility

Keep IDs stable after a theme ships. Changing an ID disconnects the schema from existing saved values.

Choose a setting type

Use the following value controls in section and block schemas. Where an alias is shown, use one spelling consistently within a theme.

Text and URL

Type	Use
`text`, `plaintext`	Short plain text
`textarea`	Longer plain text
`rich_text`, `richtext`	Formatted content
`html`, `html_textarea`	HTML content
`url`	A link

Numbers and choices

Type	Use
`number`	Numeric input
`range`	Bounded numeric slider
`select`	Dropdown choice
`radio`	Visible single choice
`checkbox`	Boolean choice

A range should define its bounds and increment:

{
  "type": "range",
  "id": "columns",
  "label": "Columns",
  "min": 2,
  "max": 5,
  "step": 1,
  "unit": "items",
  "default": 3
}

Use label and value for each explicit select or radio choice:

{
  "type": "select",
  "id": "alignment",
  "label": "Alignment",
  "options": [
    { "label": "Left", "value": "left" },
    { "label": "Center", "value": "center" }
  ],
  "default": "left"
}

Visual and media

Type	Use
`color`, `color_background`	Color value
`font`, `font_picker`	Font choice
`image`, `image_picker`	Image choice
`video_picker`	Video choice
`media_picker`	Media choice
`text_alignment`	Text alignment

Layout

Type	Use
`media_fit`	Media fit behavior
`corner_radius`	Per-corner radius values
`padding`	Spacing values
`border`	Border configuration
`gradient_overlay`	Gradient overlay configuration

Composite controls can return structured values. Inspect the selected value before you interpolate one directly into CSS.

Organization

Use header to divide a long settings panel:

{
  "type": "header",
  "content": "Card appearance"
}

A header organizes controls. It does not create a value that you read in Liquid.

Resource selectors

Fluid resolves the following setting types into Liquid resource values:

Type	Resolved value
`product`	One product
`variant`	One product variant
`collection`	One collection
`category`	One category
`enrollment_pack`	One enrollment pack
`media`	One medium
`link_list`	One navigation menu
`product_list`	Several products

The saved identifier resolves to a resource value before Liquid reads the setting:

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

{% assign featured_product = section.settings.featured_product %}
{% if featured_product %}
  <a href="{{ featured_product.url }}">{{ featured_product.title }}</a>
{% endif %}

Use product_list when the editor should choose several products. Iterate the resolved value:

{% for item in section.settings.featured_products %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

{
  "type": "product_list",
  "id": "featured_products",
  "label": "Featured products"
}

Define inline blocks

Inline blocks belong to one section. A block definition needs type and name when it defines settings.

{
  "name": "Testimonials",
  "max_blocks": 8,
  "blocks": [
    {
      "type": "testimonial",
      "name": "Testimonial",
      "limit": 8,
      "settings": [
        {
          "type": "textarea",
          "id": "quote",
          "label": "Quote",
          "default": "The daily essentials fit naturally into my routine."
        },
        {
          "type": "text",
          "id": "author",
          "label": "Author",
          "default": "Jordan Lee"
        }
      ]
    }
  ]
}

Block settings must be an array. Duplicate block types are ambiguous and produce a validation warning. Duplicate setting IDs produce an error. Render inline blocks from section.blocks:

{% for block in section.blocks %}
  <blockquote {{ block.fluid_attributes }}>
    <p>{{ block.settings.quote }}</p>
    <cite>{{ block.settings.author }}</cite>
  </blockquote>
{% endfor %}

Standalone block references contain only type. Use @theme to accept public standalone blocks and @app to accept compatible extension blocks. See blocks and components for rendering and nesting patterns.

Add presets

A preset can provide a display name, picker category, initial settings, and initial blocks.

{
  "presets": [
    {
      "name": "Customer stories",
      "category": "Social proof",
      "settings": {
        "heading": "Loved by our community"
      },
      "blocks": [
        {
          "type": "testimonial",
          "settings": {
            "quote": "The setup was quick and the results were easy to understand.",
            "author": "Morgan Ruiz"
          }
        }
      ]
    }
  ]
}

Use preset values that match IDs declared in the section and block schemas. A preset does not add new setting definitions.

Reuse option groups

Use an option group when several section or block settings should share a choice list defined by the root theme. This keeps choices such as type scales consistent across the editor. First, add option_group metadata to settings in config/settings_schema.json:

[
  {
    "name": "Typography",
    "settings": [
      {
        "type": "range",
        "id": "text_small",
        "label": "Small text size",
        "min": 10,
        "max": 24,
        "step": 1,
        "default": 14,
        "option_group": {
          "id": "type_scale",
          "label": "Small",
          "value": "text-small"
        }
      },
      {
        "type": "range",
        "id": "text_large",
        "label": "Large text size",
        "min": 18,
        "max": 48,
        "step": 1,
        "default": 28,
        "option_group": {
          "id": "type_scale",
          "label": "Large",
          "value": "text-large"
        }
      }
    ]
  }
]

Each matching option_group.id contributes one choice. The editor uses option_group.label as the choice label and option_group.value as its saved value. Duplicate values are collapsed to the first matching choice. Then set options to the plain option-group ID:

{
  "type": "select",
  "id": "heading_size",
  "label": "Heading size",
  "options": "type_scale",
  "default": "text-large"
}

Use only letters, numbers, _, and - in an option-group ID. If the group is missing or malformed, the editor cannot resolve choices for the setting. An explicit options array continues to work and takes precedence over option-group resolution.

Do not use a Liquid expression or an object in options to reference an option group. Use the plain group ID, such as "type_scale".

See root theme configuration for the rest of the settings flow.

Validate before publishing

Before you publish a schema:

Confirm that the schema body is valid JSON.
Give each value-producing setting a unique, non-empty ID.
Use only supported setting types.
Define block settings as an array.
Give inline blocks a name.
Confirm that preset values match declared IDs and block types.
Confirm that named standalone blocks exist.
Test default and edited values in the visual editor.

Run fluid theme lint --json to catch schema and reference problems before you push. See the CLI guide for the complete local workflow.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Build theme schemas

Define a section schema

Define a setting

Choose a setting type

Text and URL

Numbers and choices

Visual and media

Layout

Organization

Resource selectors

Define inline blocks

Add presets

Reuse option groups

Validate before publishing

​Define a section schema

​Define a setting

​Choose a setting type

​Text and URL

​Numbers and choices

​Visual and media

​Layout

​Organization

​Resource selectors

​Define inline blocks

​Add presets

​Reuse option groups

​Validate before publishing

Define a section schema

Define a setting

Choose a setting type

Text and URL

Numbers and choices

Visual and media

Layout

Organization

Resource selectors

Define inline blocks

Add presets

Reuse option groups

Validate before publishing