block

Renders a reusable theme block directly from a Liquid template.

A block is a reusable piece of a page, with markup, behavior, accessibility attributes, and theme editor settings kept together in one Liquid file. A Liquid template can render these theme blocks directly with {% block %}, in addition to blocks that merchants add through the theme editor.

Use {% block %} the same way that {% render %} renders a snippet: name the block file, pass any named parameters it accepts, and optionally provide body content. Because the template names each block, you can read a page's structure as a tree of blocks in the template itself. Page-specific content stays in the template that calls the block.

Basic syntax

The block name maps to a file in blocks/. For example, {% block 'container' %} renders blocks/container.liquid.

A template composes its page by calling blocks. The following template puts a heading inside a container block:

{% block 'container' %}
  <h1>Welcome</h1>
{% endblock %}

Everything between the opening and closing tags is the block's body content. The block file is written in Liquid, and it prints that body content with {{ content }}:

{% doc %}
  @param {string} [tag] - The HTML element to render.
  @param {string} [class] - A CSS class to add to the element.
  @param {string} [content] - The optional body content.
{% enddoc %}

{% assign tag = tag | default: 'div' %}

<{{ tag }} class="{{ class }}">
  {{ content }}
</{{ tag }}>

{% schema %}
{
  "name": "t:blocks.container",
  "settings": []
}
{% endschema %}

Use {% doc %} to document the named parameters the block accepts and to show how to call it. {% doc %} is documentation only: it doesn't declare, validate, or bind parameters. A parameter that's declared only in {% doc %} doesn't touch block.settings, so the block reads it only as the plain variable, like foo, never as block.settings.foo.

Always document content in {% doc %} and indicate whether it's required or optional. Use @param {string} content for required body content and @param {string} [content] for optional body content.

Use {% schema %} for settings in the theme editor, such as appearance choices, resource pickers, and contextual component settings.

Passing parameters

Pass named parameters after the block name, like you do with {% render %}. Each parameter is available as a variable inside the block, and the block's Liquid code decides what it does.

{% block 'container', tag: 'header', class: 'site-header' %}
  <h1>Page title</h1>
{% endblock %}

This call passes a tag and a class, which the block can use to choose its HTML element and add CSS classes. class has no special platform behavior, so your styling stays visible in the Liquid that renders the HTML.

Schema settings

A block's {% schema %} defines its theme editor settings, which the block reads as block.settings.<id>. A merchant usually sets these values in the theme editor. When a parameter has the same name as a setting that the schema declares, the parameter also sets that setting, which is useful when the template already knows the value. A parameter with no matching setting is only a variable.

For example, if the button schema declares a variant setting, this call makes button-primary available inside the block as both variant and block.settings.variant:

{% block 'button', variant: 'button-primary' %}
  Add to cart
{% endblock %}

Inside blocks/button.liquid, both reads return button-primary:

{{ variant }}
{{ block.settings.variant }}

One call can mix parameters that map to settings with parameters that don't:

{% block 'product-card',
  class: 'featured-product',
  product: product
%}
{% endblock %}

For how a block declares and reads settings, see block schema.

Arrays

A block parameter can take a literal array for a short list that lives in the template.

For a direct parameter, list the values inline:

{% block 'badge-list',
  badges: ['New arrival', 'Low stock', 'Online only']
%}
{% endblock %}

The same works for a parameter that maps to a schema setting:

{% block 'collection-list',
  collections: [collections['summer'], collections['sale']]
%}
{% endblock %}

Note: Inline literal arrays are specific to the <code>{% block %}</code> tag. Other tags, such as <code>{% render %}</code> and <code>{% partial %}</code>, don&#39;t accept an array written directly in the tag.

Body content

The content between {% block 'name' %} and {% endblock %} is the block's body content, and the block prints it with {{ content }}.

Body content can be plain markup, other blocks, or both. For example, a product template passes a heading and a nested button block into a container:

{% block 'container' %}
  <h1>{{ product.title }}</h1>
  {% block 'button', type: 'submit', class: 'button--full-width' %}
    Add to cart
  {% endblock %}
{% endblock %}

When a block only displays text or markup, pass it as body content instead of adding parameters like title, body, or heading. Add a parameter only when the block needs to do something with the value, like change how it renders or read the data you pass.

Where you can use the tag

Use {% block %} in layout/ and templates/ files.