Shopify Partners

How To Work With Shopify Theme Blocks

how-to-work-with-shopify-theme-blocks

When creating storefront experiences on Shopify it’s crucial to include options for merchants to customize their theme and unlock opportunities to expand a store’s potential. Shopify Developers can build a wide range of flexibility into themes by working with section blocks that add functionality, and empower merchants to control the design of their store. 

As we saw from our earlier article on How to create your first Shopify theme section, the introduction of Online Store 2.0 allows sections to be moved around any page of a store. What makes blocks different to sections is that they allow elements to be repositioned within a section.

In this article we’ll look at how to build basic blocks into a section, explore best practices to follow, and explain how app blocks can improve the merchant experience when enhancing the functionality of their store. We’ll also demonstrate how to implement blocks for most elements of a page, and demonstrate real-life examples of this approach from our source-available Dawn theme.

In this article, we will:

  • Look at how to build basic blocks into a section
  • Demonstrate how to implement blocks for most elements of a page
  • Explore how app blocks can improve the merchant experience when enhancing the functionality of their store
  • Share best practices to follow
  • Demonstrate real-life examples of this approach from our source-available Dawn theme

Grow your business with the Shopify Partner Program

Whether you offer web design and development services or want to build apps for the Shopify App Store, the Shopify Partner Program will set you up for success. Join for free and access revenue share opportunities, developer preview environments, and educational resources.

Sign up

What are theme blocks?

Illustration of six example theme blocks, including images of shoes and a video player.

Blocks are modules of content that can be added, removed, and reordered within a section. This allows merchants to have granular control over the look and feel of every aspect of their online store. Each section can have a maximum of 16 blocks per section. 

A range of different types of blocks can be added to sections, and the positions of these blocks can be changed, all from the theme editor. A block could be an image, a video, custom text, or any of the input setting types options outlined in our developer documentation

It’s important to have a clear vision and purpose for each section when deciding what types of blocks to implement, so that your theme is intuitive to use and prevents merchants from negatively impacting the layout of their store. An option to add a newsletter signup block might not be suitable in a featured product section, for example, but an option to add a custom text block could be useful in this context.

“It’s important to have a clear vision and purpose for each section when deciding what types of blocks to implement, so that your theme is intuitive to use and prevents merchants from negatively impacting the layout of their store.”

When building Shopify themes, you can define which elements of a page can be blocks, and set up rules to determine how each block appears and what settings a block could contain. Later in this article we’ll look at the benefits of turning almost all elements of a section into a block. 

Since blocks can be repeatable, it’s crucial to set limits where appropriate, so you can avoid any user-interface pitfalls. For example, you could create a block with video content. While it could be tempting to allow a large number of video blocks to be added to this section, doing this would impact site-loading times, as well as clutter the page. Instead, it could be wiser to limit this to displaying only one video. With great power comes great responsibility!

You might also like: Tips for an Efficient Shopify Theme Review Process.

Building basic theme blocks 

When building out blocks, you’ll be spending some time within the schema area of your section files, defining the various values and settings of your blocks. If you’re not already familiar with the format of the section schema, you can learn how attributes and properties are organized using JSON in our developer documentation

In our case, we’re going to create a very simple footer to demonstrate how multiple blocks can be included in a section. The easiest way to start may be to look at the full section, and then analyze each individual piece in isolation:

In the example above we have two content elements that we’d like to be available in our simple footer—a hyperlink and a custom text field. Each of these elements is wrapped in their own container, with classes of “link” and “text.” We’ll also use the block.shopify_attributes to add data attributes to the element. The theme editor’s JavaScript API uses a block’s shopify_attributes to identify blocks and listen for events. 

Similar to sections, block objects are added to Liquid section files, and its settings are defined within the schema tags. With blocks, the syntax of these objects look like {{ block.settings.id }} where the id is referenced in the schema section.

In the case of our link block, we have two settings which we’ll reference within the section schema: the URL of the link (block.settings.linkurl), and the hyperlinked text (block.settings.linktext). 

What’s also very important is that the block containers are wrapped in a {% for %} loop, which iterates through each block in section.blocks. You can see this {% for %} loop near the top of our section file:

{% for block in section.blocks %} 

Inside this forloop we’ll use the case and when control flow tags to render the individual blocks. We can set up conditions that target the type of each block, and will output the markup when a merchant adds a specific block on the theme editor. 

This is how the control flow tags would be set up for our link and custom text blocks:

In our first block element, we’re going to output a link, which means we can use the link_to Liquid URL filter to generate an HTML link. When we are creating our settings for this block, the link url will be the parameter that is passed to this filter, to generate the link. 

If we look at the section schema we can see that there’s a limit to the number of blocks that can be added: "max_blocks": 8,. This means a merchant can add any combination of eight available blocks. It’s also worth remembering at this point that the max limit for blocks in a section is 16. 

Next we have the blocks attribute where we can create arrays for our two blocks. We can assign a type for each block (this can be any value that you decide), as well as a name which will appear on the theme editor, and settings for the block which form their own separate array. 

Each block setting has its own id that we can reference in the markup, as well as a type to define what kind of setting it is, and a label that will appear in the theme editor UI. All available input settings for the block setting type attribute can be found on our developer docs

Our link block has two settings: to allow a merchant to populate a URL and to input text for the hyperlink. 

Our custom text block only has one setting, which is to include multi-line text, thanks to our textarea input type, and we can reference this setting in our markup with the custom-text-field ID (block.settings.custom-text-field). 

There are no presets in this section, as it is a static footer section. So we’ll need to include the section within the theme.liquid layout file using the section tag that references the name of the file. In my case, this could look something like:

{% section 'footer-simple' %}

Once this is added, we’ll see the section appear on the storefront, and the blocks can be customized and repositioned on the theme editor. 

The gif displays a simple footer section that contains basic blocks. The section can have a custom text block and a link block. When added these can be rearranged.
A simple example of how blocks could be arranged on a footer section.

You’ll notice that any combination of links and custom text elements can be added up to our specified limit of eight. While CSS does need to be added to our container classes so the blocks are styled appropriately, this is now a functional section that demonstrates how you can build more complex configurations of blocks for your theme. 

If you’d like to see a more comprehensive version of a footer section that utilizes blocks, you can explore Dawn’s footer in this GitHub repo.

You might also like: What it Takes to Build for Success on the Shopify Theme Store.

Using theme blocks for most elements on a section 

Since merchants can have a wide range of layout requirements, it’s good practice to “bake in” as much flexibility and customizable options as possible when developing your theme. Section blocks allow developers to achieve this, and there may be areas of the online store where you’ll want to give very granular control over most elements of a section. 

An example of one of these areas would be the product form or main product section. This is one of the most crucial areas of a store—and an area where merchants commonly need a high level of control. In fact, one of the requirements for submitting a theme to the Shopify Theme Store is that themes must support blocks for all or most elements on the main section of the Product page.

“One of the requirements for submitting a theme to the Shopify Theme Store is that themes must support blocks for all or most elements on the main section of the Product page.”

In practice, this means elements such as the product title, price, product description, vendor, and buy buttons should each be a separate block. This approach allows merchants to reposition any of these elements around the page to suit their own unique design preferences. We can see how this appears on the Dawn theme:

The GIF displays a main product section where each individual element is a separate section. Each section can be rearranged and the example shows the vendor, descriptions, and variant picker being moved vertically on the section.
An example of how a main product section could be set up with each block element being customizable.

By dragging and dropping elements, merchants can quickly find the look and feel they want for their product page, without having to dive into settings or edit the code of their theme. To achieve this effect, we can take each individual element and re-create it as a block. 

For example, part of a simple main product section could be written as follows:

If we want to add block support for the product title, product price, product vendor, and product description, we would need to first add the “blocks” property within the section schema and create JSON objects for each of the elements. 

Next we would wrap all the HTML and Liquid elements in the same {% for %} loop and case/when statements that we used earlier that will iterate over blocks in the section to render each of our blocks:

Now all of our elements are blocks, but if we navigate to the product page, we won’t see them on the page, although they will be selectable blocks on the theme editor. The final step in this process is to edit the product.json template file to define which blocks appear by default, and to assign a default order to each block. 

Within the JSON template we would add the following to determine which blocks should be added by default, and the block order:

Once this is added, the entire product.json file should appear like this:

Now, when we navigate to the product page, we see our elements appearing and they can be repositioned vertically within the section. 

The GIF displays a basic main product section where the price, vendor, and description blocks are rearranged vertically on the section.
A simple example of how a main product section could be set up to allow each element to be repositioned.

This process can be repeated for any other elements on a page that merchants may need to drag and drop. For a more comprehensive example of this approach, you can explore the main product section of our Dawn theme

Adding support for App blocks

The launch of Online Store 2.0 introduces theme app extensions, an improved approach to how apps integrate with the storefront. Theme app extensions allow app developers to inject inline content and components on a page as an app block, which merchants can add and configure directly through the theme editor. 

In order for an app block to be added to a page, a section will need to support app blocks, by including it in the section schema, and adding a render tag in the markup. Theme developers can also create an apps.liquid section specifically to wrap app blocks.

“When submitting a theme to the Shopify Theme Store, it’s a requirement that the main product section and featured product section both have support for app blocks.”

When submitting a theme to the Shopify Theme Store, it’s a requirement that the main product section and featured product section both have support for app blocks. Ideally you could go even further and add support for app blocks to other appropriate sections, such as the cart section. This will increase your theme’s compatibility with apps, and improve the merchant experience overall. 

All app blocks have a type of @app so the approach to add support for app blocks will be standard across all apps and themes. The first step is to define a block of this standard type @app in the section schema. If we look at our earlier example of the main-product.liquid section, this could appear like this:

Next we’ll need to create a new when statement for the app block inside our existing section.blocks forloop and use {% render block %} so the app block is accessible on the theme editor. 

Now when you navigate to the theme editor and customize this section, we’ll be able to add our app blocks. Only installed apps that have been updated to use theme app extensions will be available here. 

The GIF displays a section where two app blocks are available when
When an app block is active on a store, it will be available in the “Add block” menu. 

Adding support for app blocks can make your theme stand out, and enhances the general usability of your theme for merchants. Developers can test out app blocks with the demo product reviews app which has been migrated to use theme app extensions. 

“Adding support for app blocks can make your theme stand out, and enhances the general usability of your theme for merchants.”

Unlocking opportunities with blocks

Now that you’ve seen how to support blocks in your themes, you can add endless options to merchants’ stores. 

To learn more about UX considerations for how blocks should appear and be designed, check out our developer documentation on block layouts. When building out your blocks it’s also highly recommended to test on different screen sizes to ensure all your elements are displaying as expected. 

By implementing blocks on sections, allowing elements to be moved around main page sections, and adding support for app blocks, you can ensure that you’re providing merchants with robust themes that are flexible and functional. 

This article originally appeared on the Shopify Web Design and Development blog and is made available here to educate and cast a wider net of discovery.
I'm also on