<Picker name="framework">
<PickerOption name="liquid" label="Liquid" />
</Picker>
<Overview>
Learn how to build a basic theme block and add it to a section and another block file.
Theme blocks are blocks that are defined at the theme level. You can reuse theme blocks across different sections of the theme, unlike [section-defined blocks](/docs/storefronts/themes/architecture/blocks/section-blocks) that can only be used within the section where they're defined. Additionally, theme blocks can be nested within other theme blocks to create hierarchy.
</Overview>
<Requirements>
<Requirement href="/docs/storefronts/themes/architecture/blocks" label="Understand Blocks at Shopify" />
<Requirement href="/docs/storefronts/themes/getting-started/create" label="Create a Theme" />
</Requirements>
<StepSection>
<Step>
## Create a theme block
At the end of this tutorial, you should have a text block that can be reused across different sections and blocks of the theme. You will add it to a Custom Section and a Group block.
<Substep>
### Add a blocks folder
Theme blocks are Liquid files that are defined in the `blocks` directory of the theme. To create a theme block, add a Liquid file in the `/blocks` folder of your theme.
If your theme doesn't have a `/blocks` folder yet, then add one at the root of your theme.
Add a `text.liquid` file to the `/blocks` folder.
<CodeRef
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/text.liquid"
/>
</Substep>
<Substep>
### Write the markup
Theme block files contain markup.
The markup is any HTML or Liquid content that you want to include in the block.
<CodeRef
tag="block.markup"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/text.liquid"
/>
</Substep>
<Substep>
### Write the schema
Theme block files contain a schema.
The schema is the ```{% schema %}``` Liquid tag, which is used to configure settings and attributes of the block. [Learn how to write block schema](/docs/storefronts/themes/architecture/blocks/theme-blocks/schema).
<Notice type="info" title="Tip">At this step, you'll be able to reference the theme block in a section file with [block targeting](/docs/storefronts/themes/architecture/blocks/theme-blocks/targeting). To make this block display in the theme editor's block picker, you need to [add a block preset](/docs/storefronts/themes/architecture/blocks/theme-blocks?extension=liquid#add-a-block-preset).</Notice>
<CodeRef
tag="block.preset"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/text.liquid"
/>
</Substep>
<Substep>
### Use Liquid objects in blocks
Blocks use a few key liquid objects:
* Theme blocks reference a [`block`](https://shopify.dev/docs/api/liquid/objects/block) object, which contains the properties and setting values of the block.
* Theme blocks can reference the [`section`](https://shopify.dev/docs/api/liquid/objects/section) object of the section that rendered the theme block.
* Theme blocks have access to [global objects](https://shopify.dev/docs/api/liquid/objects).
In this Text block example, this block references the settings attribute of the block object.
Theme blocks cannot access variables created outside the block and cannot be passed variables like when using a [snippet](https://shopify.dev/docs/storefronts/themes/architecture#snippets).
<CodeRef
tag="block.markup"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/text.liquid"
/>
</Substep>
<Substep>
### Add a block preset
[Presets](/docs/storefronts/themes/architecture/blocks/theme-blocks/schema#presets) need to be defined in order for the theme block to be available for merchants in the theme editor block picker. You can author multiple presets for the same theme block.
In this example, the text theme blocks has two presets called Text and Content.
<Codeblock title="Block presets">
```json
"presets": [
{ "name": "Text" },
{
"name": "Content",
"settings": {
"text": "Hello, World!"
}
}
]
```
</Codeblock>
<CodeRef
tag="block.preset"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/text.liquid"
/>
</Substep>
</Step>
<Step>
## Use theme blocks in sections
After theme blocks are defined in your theme, you need to update the theme's sections to render blocks.
<Notice type="info" title="Tip">Sections can either [define blocks locally](/docs/storefronts/themes/architecture/blocks/section-blocks) or opt-in to supporting theme blocks, but they can't support both simultaneously.</Notice>
<Substep>
### Render the blocks in Liquid
Render the blocks in Liquid using
<Codeblock title="Render blocks in liquid">
```javascript
{% content_for 'blocks' %}
```
</Codeblock>
<CodeRef
tag="section.render_blocks"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/sections/custom-section.liquid"
/>
</Substep>
<Substep>
### Update the section schema
To accept all theme blocks in a section, add the type `@theme` to the [blocks attribute](/docs/storefronts/themes/architecture/sections/section-schema#blocks) of the [schema](/docs/storefronts/themes/architecture/sections/section-schema) of that section. To be more restrictive about which blocks can be use in specific sections, use [block targeting](/docs/storefronts/themes/architecture/blocks/theme-blocks/targeting).
<Codeblock title="blocks attribute">
```json
"blocks": [{ "type": "@theme" }, { "type": "@app" }],
```
</Codeblock>
<CodeRef
tag="section.blocks"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/sections/custom-section.liquid"
/>
</Substep>
</Step>
<Step>
## Nest blocks in theme blocks
Theme blocks can accept other theme and app blocks as children.
<Substep>
Theme blocks use the [`blocks` attribute](/docs/storefronts/themes/architecture/blocks/theme-blocks/schema#blocks) of their schema and assemble different configurations of these child blocks using the [`presets` attribute](/docs/storefronts/themes/architecture/blocks/theme-blocks/schema#presets).
In this example, the Group block has a preset called Column which is nesting the Text block using the `presets` attribute.
<Codeblock title="Group block's Column preset nests Text blocks">
```json
{
"name": "Column",
"settings": {
"color_scheme": "scheme-3"
},
"blocks": [
{
"type": "text",
"settings": {
"text": "<h3>Hello, world!</h3>"
}
},
{
"type": "text",
"settings": {
"text": "<p>How's it going?<\/p>"
}
}
]
}
```
</Codeblock>
<CodeRef
tag="nesting.block_schema"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/group.liquid"
/>
</Substep>
<Substep>
Each block's content is rendered by the liquid tag
<Codeblock title="Render blocks in liquid">
```javascript
{% content_for 'blocks' %}
```
</Codeblock>
The content is rendered in the order that's stored in the [JSON template](/docs/storefronts/themes/architecture/templates/json-templates). This is the same rendering mechanism sections use for blocks.
<CodeRef
tag="nesting.block_render"
href="https://github.com/Shopify/liquid-docs-code-samples/blob/main/blocks/group.liquid"
/>
</Substep>
<Notice type="info" title="Tip">Block presets can refer to other theme blocks within the theme. This example refers to the `/blocks/text.liquid` Liquid file created earlier in this tutorial. Learn more about [theme block presets](/docs/storefronts/themes/architecture/blocks/theme-blocks/schema).</Notice>
</Step>
</StepSection>
<NextSteps>
## Next Steps
The examples above demonstrate basic theme blocks usage. Theme blocks support several more advanced features to enhance the merchant experience as well as provide flexibility to theme developers.
<CardGrid>
<LinkCard href="/docs/storefronts/themes/architecture/blocks/theme-blocks/schema">
#### Theme block schema
Learn how to configure theme block settings and attributes through their schema.
</LinkCard>
<LinkCard href="/docs/storefronts/themes/architecture/blocks/theme-blocks/targeting">
#### Theme block availability with targeting
Learn how to use targeting in order to restrict which theme blocks can be added by merchants to sections and blocks that accept nested blocks.
</LinkCard>
<LinkCard href="/docs/storefronts/themes/architecture/blocks/theme-blocks/static-blocks">
#### Layout control with static blocks
Learn how to have stricter control over the layout of theme blocks and sections using static blocks.
</LinkCard>
<LinkCard href="/docs/storefronts/themes/architecture/blocks/theme-blocks/dynamic-sources">
#### Dynamic sources
Learn how to enable more flexibility for merchants by connecting theme blocks to dynamic sources.
</LinkCard>
</CardGrid>
</NextSteps>