The Power of Reusability: A Guide to Shopify's New Theme Blocks

For years, Shopify theme developers have relied on a combination of sections and snippets to create reusable UI elements. While effective, this system often led to a dilemma: should you create a massive, monolithic section with dozens of settings, or juggle a complex web of snippets?

With the release of Theme Blocks, Shopify has introduced a powerful new primitive that fundamentally changes the way we build themes. Theme Blocks allow you to create truly independent, reusable components with their own settings, schema, and logic, which can then be used across multiple sections.

This is the feature developers have been waiting for, and it has the potential to drastically increase your development speed and improve the long-term maintainability of your codebase.

Let’s dive into what Theme Blocks are and how to build your first one.

---

What Are Theme Blocks?

At its core, a Theme Block is a .liquid file that lives in a new blocks directory at the root of your theme. Each block is a self-contained component with its own:

• Liquid Markup: The HTML structure of the component.
• Schema: A set of settings that can be configured in the theme editor, just like a section.
• CSS and JavaScript: Scoped styles and scripts for the component.

Think of them as “micro-sections” or “super-snippets.” They combine the reusability of a snippet with the user-configurability of a section.

---

Practical Example: Building a Reusable “Button” Block

Buttons are one of the most common UI elements in any theme, and they are a perfect candidate for a Theme Block.

Step 1: Create the Block File

First, create a new file at /blocks/button.liquid.

Step 2: Add the Liquid Markup and Schema

Inside this file, you’ll add the HTML for the button and the schema that defines its settings.

{% comment %} /blocks/button.liquid {% endcomment %}

{% if block.settings.button_text != blank %}
  <a
    href="{{ block.settings.button_url }}"
    class="block-btn {{ block.settings.button_type }} {{ block.settings.button_color }}"
  >
    {{- block.settings.button_text -}}
  </a>
{% endif %}

{% schema %}
{
  "name": "Button",
  "settings": [
    {
      "type": "text",
      "id": "button_text",
      "label": "Button Text"
    },
    {
      "type": "url",
      "id": "button_url",
      "label": "Button URL"
    },
    {
      "type": "select",
      "id": "button_type",
      "label": "Button Type",
      "default": "btn--primary",
      "options": [
        { "value": "btn--primary", "label": "Primary" },
        { "value": "btn--secondary", "label": "Secondary" }
      ]
    }
  ]
}
{% endschema %}

This is a huge improvement! All the logic and settings for a button are now encapsulated in a single, reusable file. If you need to add a new button style, you only have to update it in one place, and the change will propagate everywhere the block is used.

---

Step 3: Using Your Theme Block in a Section

You can use your new button block in any section in two ways: dynamically or statically.

Dynamic Blocks

This approach allows merchants to add, remove, and reorder blocks within a section, similar to how blocks have always worked.

In your section file (e.g., custom-hero.liquid), you define that the section can accept button blocks in its schema.

{% for block in section.blocks %}
  {% case block.type %}
    {% when 'button' %}
      {% render block %}
  {% endcase %}
{% endfor %}

{% schema %}
{
  "name": "Hero",
  "blocks": [
    {
      "type": "button"
    }
  ]
}
{% endschema %}

The {% render block %} tag is the magic here. It tells Shopify to render the theme block and make its settings available in the theme editor.

Static Blocks

This approach is for when you want a block to always be present in a section, but you still want its settings to be configurable.

In your section file, you can render a block statically using the {% content_for 'block' %} tag.

<div class="hero-content">
  <h2>{{ section.settings.title }}</h2>
  {% content_for 'block', type: 'button', id: 'hero_button' %}
</div>

{% schema %}
{
  "name": "Hero",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Heading"
    }
  ]
}
{% endschema %}

In this example, the button’s settings will appear directly within the “Hero” section’s settings in the theme editor. The id is crucial as it ensures the settings are saved uniquely for this instance of the block.

---

Final Thoughts: A New Era of Theme Architecture

Theme Blocks are a fundamental shift that enables a more modular, component-based approach to Shopify theme development. They solve the age-old problem of code duplication and lead to themes that are:

• Faster to build: Assemble new sections from your library of pre-built blocks.
• Easier to maintain: Update a component in one place, and the changes apply everywhere.
• More powerful for merchants: Offer greater flexibility without creating overwhelmingly complex sections.

If you’re building Shopify themes, it’s time to embrace Theme Blocks. They are the foundation of modern theme architecture.

❓ What will be the first reusable component you build as a Theme Block?