Block tag

A block is a reusable piece of a page, with markup, behavior, accessibility attributes, and theme editor settings kept together in one Liquid file. These are the same theme blocks you already use. What's new is how you place them on a page: instead of only adding a block through the theme editor, a Liquid template can render one directly with {% block %}.

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.

Anchor to Basic syntaxBasic 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:

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 {{ block.content }}:

The {% schema %} tag is where a block declares its theme editor settings, and this one has none yet. See Authoring a block file for {% schema %} and {% doc %}.

Anchor to Passing parametersPassing parameters

Pass named parameters after the block name, like you do with {% render %}. The block's Liquid code decides what each one does.

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.

Anchor to Schema settingsSchema 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. From a {% block %} call, you can set them directly with block.settings.* parameters, which is useful when the template already knows the value.

This sets the block's variant setting to button-primary, the same value the block would otherwise read from the theme editor.

Pass named parameters and settings together when the template needs both:

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

Anchor to ArraysArrays

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:

The same works for a block.settings.* parameter that maps to a schema setting:

Anchor to Body contentBody content

The content between {% block 'name' %} and {% endblock %} is the block's body content, and the block prints it with {{ block.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:

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.

Anchor to Authoring a block fileAuthoring a block file

A block file contains Liquid markup and can include the familiar {% doc %} and {% schema %} tags:

• Use {% doc %} to document the named parameters the block accepts and to show how to call it.
• Use {% schema %} for settings in the theme editor, such as appearance choices, resource pickers, and contextual component settings.

Use a parameter for a value the template controls, and a schema setting for a value a merchant controls. For example, the template sets the button's type, while a merchant picks its variant in the theme editor:

Keep a block focused. Aim for six settings or fewer, and if it needs many more, split it into smaller blocks. Anything the template controls should be a parameter, not a setting.

When a value can come from either a parameter or a setting, you choose the order in the block's Liquid. For example, this button uses a variant parameter if the template passes one, then falls back to the variant setting, and finally a default:

Anchor to Choosing between block, content_for, and renderChoosing between block, content_for, and render

These tags all render reusable code. Which one you use comes down to who controls the page and what you're rendering.

• {% block %}: Use when the template controls the page. You name the block and pass it parameters and body content, so the whole composition stays in Liquid you can read top to bottom.
• {% content_for %}: Use when a merchant controls the page by adding and arranging blocks in the theme editor, which Shopify stores in a JSON template.
• {% render %}: Use for a snippet in snippets/, for internal, repeated Liquid that has no theme editor settings.