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
`slots`	Named child-section targets in a container section, where container support is enabled
`max_blocks`	Maximum combined number of blocks
`presets`	Initial content and picker variants
`enabled_on`	Template types where the section is allowed
`disabled_on`	Accepted, but not yet applied. Use `enabled_on`

Limit a section to certain templates

Use enabled_on to allow a section only on the templates you list. In the Page Editor, the section then appears under Not available here on every other template. This section is allowed only on product templates:

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

A section without enabled_on is available on every template. Lint accepts disabled_on, but the editor ignores it, so list the allowed templates in enabled_on instead.

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 above the control
`default`	Initial value, in the shape that the type saves
`info`	Help text shown below the control
`options`	Choices for `select`, `radio`, and `font_picker`: an array, or an option group ID
`min`, `max`, `step`	Limits for `range` and `number`
`limit`	Maximum number of items in a multi-select resource picker
`content`	Title of a `header`
`visible_if`	Condition that shows or hides the control. See Show settings conditionally

Section and block controls ignore unit and placeholder. The theme panel reads unit on typography presets. See settings schema. Keep IDs stable after a theme ships. Changing an ID disconnects the schema from existing saved values.

Choose a setting type

Section and block settings render the same control for each type, with one exception: blocks do not accept image. Use image_picker, which renders the same control in both. In a block, a type without a control renders the word Unknown instead of an input. Where an alias is shown, use one spelling consistently within a theme. Settings in config/settings_schema.json render in the theme panel, which supports fewer types. See settings schema.

Text and URL

Type	Control	Saved value
`plaintext`	Single-line input with no formatting	The text as typed
`text`	Compact rich-text editor: bold, italic, underline, strikethrough, links, alignment, text styles, and variables	An HTML fragment
`textarea`, `rich_text`, `richtext`	Full rich-text editor: everything in `text`, plus lists, code blocks, images, and indentation	An HTML fragment
`html`, `html_textarea`	Plain textarea for raw HTML	The HTML as typed
`url`	URL field with a picker for links in your store	A URL string

text is not plain text. It saves HTML, such as Free delivery on <strong>every</strong> order. Use plaintext for any value that ends up in an HTML attribute, a CSS value, a URL, or a script.

<h2>{{ section.settings.heading }}</h2>
<div class="rte">{{ section.settings.body }}</div>
<a href="{{ section.settings.button_link }}" class="button">{{ section.settings.button_label }}</a>

{% schema %}
{
  "name": "Feature",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Made for every day" },
    { "type": "richtext", "id": "body", "label": "Body" },
    { "type": "url", "id": "button_link", "label": "Button link" },
    { "type": "plaintext", "id": "button_label", "label": "Button label", "default": "Shop now" }
  ],
  "presets": [
    { "name": "Feature" }
  ]
}
{% endschema %}

The variable picker in both rich-text editors inserts a Liquid tag such as {{ company.name }}. Fluid renders Liquid tags in saved setting values before your template reads them, so the page shows the current value. The url picker lists store destinations, such as the home page, pages, products, collections, categories, posts, and media. It saves the selected destination’s URL. Editors can also type any URL.

Numbers

Type	Control	Saved value
`range`	Slider with a value field	A number
`number`	Numeric field	A number, or blank when the editor clears the field

Define min, max, and step on every range. Without them, the slider runs from 0 to 100 in steps of 1.

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

Use number for open-ended values. min, max, and step are optional; when set, the editor keeps entries between min and max.

{
  "type": "number",
  "id": "review_count",
  "label": "Review count",
  "min": 0,
  "default": 126
}

An editor can clear a number field, so give the value a fallback in Liquid:

{% assign review_count = section.settings.review_count | default: 0 %}

Choices

Type	Control	Saved value
`select`	Dropdown	The chosen option’s `value`, as a string
`radio`	Segmented buttons	The chosen option’s `value`, as a string
`checkbox`	Switch	`true` or `false`
`text_alignment`	Left, center, and right buttons	`left`, `center`, or `right`. Defaults to `left`

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"
}

Select and radio values are saved as strings, even when you write a number. Compare them with quoted values in Liquid: {% if section.settings.columns == '3' %}. To share one list of choices across several settings, use an option group.

Color and fonts

Type	Control	Saved value
`color`	Color picker with a hex field	A color string, such as `#e7f0ff`
`color_background`	Solid or linear-gradient color picker	A color string, or a `linear-gradient(...)` value
`font_picker`, `font`	Font dropdown	The chosen option’s `value`, a CSS font family

Apply a color_background value with the background property. background-color ignores gradients.

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

List the fonts a font picker offers in options, or point options at an option group. Without options, the picker offers system fonts: System UI, Apple System, Segoe UI, Roboto, Helvetica, Arial, and Sans Serif.

{
  "type": "font_picker",
  "id": "heading_font",
  "label": "Heading font",
  "options": [
    { "label": "Inter", "value": "Inter, sans-serif" },
    { "label": "Lora", "value": "Lora, serif" }
  ],
  "default": "Inter, sans-serif"
}

Images, video, and media

Type	Control	Saved value
`image_picker`, `image`	Image from the media library	The image URL
`video_picker`	Video from the media library	The video URL
`media_picker`	Image or video, plus embed options	A media object

Each picker also shows an alt text field. The editor saves alt text in a companion setting named <id>_alt, so do not declare it yourself. Choosing a new image or video clears the alt text. Render a picker’s value with the media_tag filter, which builds responsive markup and renders nothing for an empty value:

{{ section.settings.hero_image | media_tag: sizes: "(max-width: 768px) 100vw, 1200px", alt: section.settings.hero_image_alt }}

Read a media picker

A media_picker saves an object, because it carries both the file and its embed options:

{
  "url": "https://cdn.example.com/media/spring-launch.mp4",
  "fluid_media_id": 4182,
  "embed_type": "popover",
  "embed_settings": {
    "width": 560,
    "height": 315,
    "responsive": true,
    "autoOpen": false,
    "hideCta": false,
    "fairShareVisible": false
  }
}

Read url from the object: {{ section.settings.banner_media.url }}, not {{ section.settings.banner_media }}. embed_settings can be missing, so check the object before you read nested values. A positive fluid_media_id identifies a Fluid media item, which you render with the media widget. The ID can be 0 for a plain file, so compare it with > 0. Liquid treats 0 as true, so != blank does not work here.

{%- assign media = section.settings.banner_media -%}
{%- if media != blank and media.url != blank -%}
  {%- if media.fluid_media_id > 0 -%}
    <fluid-media-widget
      media-id="{{ media.fluid_media_id }}"
      embed-type="{{ media.embed_type | default: 'default' }}"
    ></fluid-media-widget>
  {%- else -%}
    {{ media | media_tag: alt: section.settings.banner_media_alt }}
  {%- endif -%}
{%- endif -%}

embed_type maps to the widget’s embed-type attribute:

`embed_type`	Behavior
`default`	Shows the media with its call-to-action options
`popover`	Shows a thumbnail that opens the media in an overlay
`inline`	Embeds the media in the page
`inline-shopping`	Embeds the media in the page with shopping enabled

See the media widget for its other attributes.

Layout

Type	Control	Saved value
`media_fit`	Dropdown: Width, Height, or Fit to Media	`width`, `height`, or `fit`
`corner_radius`	Four corners that can be linked	`{ "tl", "tr", "br", "bl", "linked" }`
`padding`	Four sides, with linkable vertical and horizontal pairs	`{ "top", "bottom", "left", "right", "verticalLinked", "horizontalLinked" }`
`border`	Width and color	`{ "width", "color" }`
`gradient_overlay`	Solid or gradient overlay with opacity	An overlay object, shown below

Corner and side values are numbers of pixels. A value linked to a theme preset is a CSS variable reference, such as var(--spacing-lg). Padding and radius presets come from the padding and corner_radius groups, and border and overlay colors from color_schema. See linked CSS presets. Add px only to plain numbers:

{%- assign pt = section.settings.padding.top -%}
{%- assign pb = section.settings.padding.bottom -%}
<section style="
  padding-top: {% if pt contains 'var' %}{{ pt }}{% else %}{{ pt | default: 0 }}px{% endif %};
  padding-bottom: {% if pb contains 'var' %}{{ pb }}{% else %}{{ pb | default: 0 }}px{% endif %};
">

A border saves its width with the unit, such as { "width": "2px", "color": "#d0d5dd" }. A gradient overlay saves an object like this:

{
  "enabled": true,
  "mode": "gradient",
  "gradientType": "linear",
  "angle": 180,
  "colors": [
    { "color": "#000000", "opacity": 0, "position": 0 },
    { "color": "#000000", "opacity": 60, "position": 100 }
  ]
}

mode is solid or gradient, and gradientType is linear or radial. opacity and position run from 0 to 100; position is optional. A color can be a hex value or a var(--...) preset reference. Render nothing when enabled is false.

Organization

Use header to group the settings that follow it:

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

Each header starts a collapsible group that runs to the next header. The group’s title is the header’s content, or its label. The first group opens by default, and settings before the first header appear above all groups. A group disappears when its header’s visible_if is false, or when every setting in it is hidden. A header organizes controls. It does not create a value that you read in Liquid.

Resource selectors

Resource pickers save record IDs. Fluid resolves the following setting types into Liquid resource values before your template reads them:

Type	Picker	Liquid receives
`product`	One product	A product
`variant`	One product variant	A variant
`collection`	One collection	A collection
`category`	One category	A category
`enrollment_pack`	One enrollment pack	An enrollment pack
`link_list`	One navigation menu	A menu with `title`, `handle`, and `menu_items`, each with `title`, `url`, and nested `sub_menu_items`
`product_list`	Several products	An array of products
`media`	No editor control	A media item

media has no control in the section or block panel. Set its value to a media ID or slug in a preset. An unset resolved setting is an empty object, or an empty array for product_list. Liquid treats an empty object as true, so test it with != blank:

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

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

Let editors choose several products

Use product_list when the editor should choose several products. Set limit to cap the selection. 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",
  "limit": 8
}

Pickers that Fluid does not resolve

These types also open a picker, but Liquid receives the saved ID, or an array of IDs:

Type	Picker	Liquid receives
`post`, `blog`	One post	A post ID
`enrollment`	One enrollment pack	An enrollment pack ID
`forms`	One form	A form ID
`products`, `products_list`	Several products	An array of product IDs
`collections`, `collections_list`, `collection_list`	Several collections	An array of collection IDs
`categories`, `categories_list`, `category_list`	Several categories	An array of category IDs
`posts`, `posts_list`, `post_list`, `blog_list`, `blogs_list`	Several posts	An array of post IDs
`enrollments`, `enrollments_list`, `enrollment_list`, `enrollment_packs_list`	Several enrollment packs	An array of enrollment pack IDs

Look the records up yourself, or use a resolved type instead.

The plural types are not aliases of the singular ones. products opens a multi-select picker and saves unresolved IDs, while product saves one product that Fluid resolves. For several resolved products, use product_list.

Types from other platforms

fluid theme lint rejects these types with Invalid settings type. Use the Fluid equivalent:

Type	Use instead
`inline_richtext`	`text`
`paragraph`	`header`, or `info` on the setting it explains
`article`	`post`
`article_list`	`posts_list`
`video`	`video_picker` or `media_picker`
`video_url`	`url`
`page`	`url`, whose picker lists pages
`color_scheme`, `color_scheme_group`	`color`
`liquid`, `metaobject`, `metaobject_list`	No equivalent

Show settings conditionally

Add visible_if to show a setting only when a condition is true. Write the condition as an expression, with or without {{ }}:

[
  {
    "type": "checkbox",
    "id": "show_button",
    "label": "Show button",
    "default": true
  },
  {
    "type": "plaintext",
    "id": "button_label",
    "label": "Button label",
    "default": "Shop the collection",
    "visible_if": "{{ section.settings.show_button }}"
  }
]

A section setting’s condition reads section.settings.<id>. A block setting’s condition can read block.settings.<id> as well as section.settings.<id>.

Syntax	Example
`==`, `!=`, `>`, `<`, `>=`, `<=`	`section.settings.layout == 'grid'`
`contains`	`section.settings.badge_text contains 'sale'`
`and`, `or`	`section.settings.show_button and section.settings.columns > 2`
`not`, `!`	`not section.settings.full_width`
Parentheses	`(section.settings.layout == 'grid' or section.settings.layout == 'list') and section.settings.show_button`

&& and || work as and and or. A value can be a setting path, a quoted string, a number, true, false, or null. and binds tighter than or. A string compared with a number compares as a number, so '3' == 3 is true.

visible_if only hides the control in the editor. A hidden setting keeps its saved value, and Liquid still receives it, so check the same condition in your template. If the editor cannot evaluate a condition, it shows the setting. The theme panel ignores visible_if.

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 }}>
    <div>{{ block.settings.quote }}</div>
    <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, and image_picker rather than image in blocks.
Use plaintext, not text, for values that go into attributes, CSS, or URLs.
Test resolved resource settings with != blank.
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.

Start here

Building blocks

Storefront features

Advanced

Member storefront

Build theme schemas

Define a section schema

Limit a section to certain templates

Define a setting

Choose a setting type

Text and URL

Numbers

Choices

Color and fonts

Images, video, and media

Read a media picker

Layout

Organization

Resource selectors

Let editors choose several products

Pickers that Fluid does not resolve

Types from other platforms

Show settings conditionally

Define inline blocks

Add presets

Reuse option groups

Validate before publishing

​Define a section schema

​Limit a section to certain templates

​Define a setting

​Choose a setting type

​Text and URL

​Numbers

​Choices

​Color and fonts

​Images, video, and media

​Read a media picker

​Layout

​Organization

​Resource selectors

​Let editors choose several products

​Pickers that Fluid does not resolve

​Types from other platforms

​Show settings conditionally

​Define inline blocks

​Add presets

​Reuse option groups

​Validate before publishing

Define a section schema

Limit a section to certain templates

Define a setting

Choose a setting type

Text and URL

Numbers

Choices

Color and fonts

Images, video, and media

Read a media picker

Layout

Organization

Resource selectors

Let editors choose several products

Pickers that Fluid does not resolve

Types from other platforms

Show settings conditionally

Define inline blocks

Add presets

Reuse option groups

Validate before publishing