Choose blocks or components

Fluid themes provide three ways to reuse markup:

Components are Liquid partials that accept values when you render them.
Inline blocks are configurable items defined and rendered by one section.
Standalone theme blocks package markup and schema for reuse across sections.

Choose the smallest primitive that gives editors the control they need.

Use a component

Create a component when you want to reuse markup without adding an editor-controlled item. Components do not have their own schema. Store each component in its own directory:

components/
├── button/
│   └── index.liquid
└── product_card/
    └── index.liquid

Render a component with named values:

{% render 'button',
  text: 'View starter collection',
  href: collection.url,
  variant: 'primary'
%}

Inside the component, use the passed values like regular Liquid variables:

{% assign button_text = text | default: 'Learn more' %}

<a class="button button--{{ variant | default: 'primary' }}" href="{{ href }}">
  {{ button_text }}
</a>

Document the accepted values in a Liquid comment at the top of the component. Give optional values a fallback. A component can render another component.

Use an inline block

Use an inline block when an item belongs to one section. Define its schema inside the section and render it from section.blocks.

<div class="feature-list">
  {% for block in section.blocks %}
    {% case block.type %}
      {% when 'feature' %}
        <article class="feature-list__item" {{ block.fluid_attributes }}>
          <h3>{{ block.settings.heading }}</h3>
          <p>{{ block.settings.description }}</p>
        </article>
    {% endcase %}
  {% endfor %}
</div>

{% schema %}
{
  "name": "Feature list",
  "blocks": [
    {
      "type": "feature",
      "name": "Feature",
      "limit": 6,
      "settings": [
        {
          "type": "text",
          "id": "heading",
          "label": "Heading",
          "default": "Flexible delivery"
        },
        {
          "type": "textarea",
          "id": "description",
          "label": "Description",
          "default": "Choose the schedule that works for you."
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Feature list",
      "blocks": [
        { "type": "feature" }
      ]
    }
  ]
}
{% endschema %}

Add {{ block.fluid_attributes }} to the block’s outer element. The editor uses these attributes to identify the selected item.

Use a standalone theme block

Use a standalone theme block when several sections need the same configurable item. A standalone block owns both its Liquid markup and its schema. Store blocks under blocks/:

blocks/
├── heading/
│   └── index.liquid
├── button/
│   └── index.liquid
└── _product_card/
    └── index.liquid

For example, blocks/heading/index.liquid can contain:

<div class="heading-block" {{ block.fluid_attributes }}>
  {{ block.settings.text }}
</div>

{% schema %}
{
  "name": "Heading",
  "settings": [
    {
      "type": "richtext",
      "id": "text",
      "label": "Text",
      "default": "<h2>Build your daily routine</h2>"
    }
  ],
  "presets": [
    { "name": "Heading" }
  ]
}
{% endschema %}

Render the section’s standalone blocks with content_for:

<section class="content-stack">
  {% content_for 'blocks' %}
</section>

{% schema %}
{
  "name": "Content stack",
  "blocks": [
    { "type": "@theme" }
  ],
  "presets": [
    {
      "name": "Content stack",
      "blocks": [
        {
          "type": "heading",
          "settings": {
            "text": "<h2>Build your daily routine</h2>"
          }
        }
      ]
    }
  ]
}
{% endschema %}

content_for 'blocks' renders each block through its own template. Do not also loop over section.blocks to render the same standalone blocks.

Control which blocks a section accepts

Add {"type": "@theme"} to accept every public standalone block in the theme. Reference a block by name when the section should accept only selected block types:

{
  "blocks": [
    { "type": "heading" },
    { "type": "button" }
  ]
}

A named reference contains type without an inline name or settings definition. Fluid reads the matching standalone block’s schema. You can combine public blocks, named references, and inline blocks:

{
  "blocks": [
    { "type": "@theme" },
    { "type": "_product_card" },
    {
      "type": "divider",
      "name": "Divider",
      "settings": [
        {
          "type": "color",
          "id": "color",
          "label": "Color",
          "default": "#d9dee8"
        }
      ]
    }
  ]
}

Keep a standalone block private

Prefix a standalone block name with _ to exclude it from @theme. Reference the private block by its exact name in sections that need it:

{
  "blocks": [
    { "type": "_product_card" }
  ]
}

Use private blocks for section-specific structure that should not appear in every compatible block picker.

Nest standalone blocks

A standalone block can accept child blocks. Inside its template, content_for 'blocks' renders the current block’s children.

<div class="card-group" {{ block.fluid_attributes }}>
  {% content_for 'blocks' %}
</div>

{% schema %}
{
  "name": "Card group",
  "blocks": [
    { "type": "@theme" }
  ],
  "settings": [
    {
      "type": "color_background",
      "id": "background",
      "label": "Background",
      "default": "#f4f7fb"
    }
  ],
  "presets": [
    {
      "name": "Card group",
      "blocks": [
        { "type": "heading" },
        { "type": "button" }
      ]
    }
  ]
}
{% endschema %}

Fluid supports two levels of block nesting. Keep the hierarchy shallow so editors can understand and reorder it.

Render a fixed block

Use the singular content_for 'block' form for a block that belongs in a fixed position:

{% content_for 'block', type: '_product_card', id: 'featured-product' %}

You can pass a nearby resource through the closest namespace:

{% content_for 'block',
  type: '_product_card',
  id: 'featured-product',
  closest.product: product
%}

The block can then read closest.product. This pattern is useful when the surrounding section controls the resource but the block controls its presentation.

Add presets

Presets provide initial settings and blocks when an editor adds a section or standalone block. They can also expose multiple configured variants in the picker.

{
  "presets": [
    {
      "name": "Primary button",
      "settings": {
        "style": "primary"
      }
    },
    {
      "name": "Outline button",
      "settings": {
        "style": "outline"
      }
    }
  ]
}

Add at least one preset when authors should be able to add the item from the editor. Use realistic defaults that produce a useful preview.

Compare the options

Capability	Component	Inline block	Standalone theme block
Own schema	No	In its section	Yes
Editor-controlled	No	Yes	Yes
Reusable across sections	Yes	No	Yes
Render with	`render`	`section.blocks`	`content_for`
Supports child blocks	Through component composition	No	Yes
Best for	Repeated markup	Section-specific items	Reusable editor content

Use a component for rendering concerns. Use a block for editor-owned content. A standalone block can render a component when you need both behaviors. See schema components for setting types and schema rules. See the developer guide for the complete theme structure.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Choose blocks or components

Use a component

Use an inline block

Use a standalone theme block

Control which blocks a section accepts

Keep a standalone block private

Nest standalone blocks

Render a fixed block

Add presets

Compare the options

​Use a component

​Use an inline block

​Use a standalone theme block

​Control which blocks a section accepts

​Keep a standalone block private

​Nest standalone blocks

​Render a fixed block

​Add presets

​Compare the options

Use a component

Use an inline block

Use a standalone theme block

Control which blocks a section accepts

Keep a standalone block private

Nest standalone blocks

Render a fixed block

Add presets

Compare the options