---
title: 'Liquid tags: block'
description: Renders a reusable theme block directly from a Liquid template.
source_url:
  html: 'https://shopify.dev/docs/api/liquid/tags/block'
  md: 'https://shopify.dev/docs/api/liquid/tags/block.md'
api_name: liquid
---

# 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](https://shopify.dev/docs/storefronts/themes/architecture/blocks) directly with `{% block %}`, in addition to blocks that merchants add through the theme editor.

Use `{% block %}` the same way that [`{% render %}`](https://shopify.dev/docs/api/liquid/tags/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:

```liquid
{% 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 }}`:

```liquid
{% 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 %}`](https://shopify.dev/docs/storefronts/themes/tools/liquid-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 %}`](https://shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/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.

```liquid
{% 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](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-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`:

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

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

```liquid
{{ variant }}
{{ block.settings.variant }}
```

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

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

For how a block declares and reads settings, see [block schema](https://shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/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:

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

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

```liquid
{% 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`:

```liquid
{% 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.

## Syntax

```oobleckTag
{% block 'name', parameter: value %}
  content
{% endblock %}
```