Shopify just released global theme blocks in January 2025, and we at Ultramarina are really excited to be one of the first theme partners to fully hop on the train, even launching our Shopify theme, Primavera, before Shopify released the Horizon themes.
As longtime developers in the Shopify ecosystem, theme blocks solved a lot of the pain points we had with developing Shopify themes. But before we get too ahead of ourselves, let’s summarize what theme blocks are.
What are Shopify theme blocks?
In what Shopify calls Online Store 2.0 architecture, themes have three basic levels of building blocks. A theme consists of templates, which can be applied to multiple pages. Templates have different sections, which contain various settings. Sections can contain one or more types of blocks, which also have settings, but only up to a single level of nesting. A section can have many blocks, but those blocks could not have other blocks.
To give an example, a website might have a Frequently Asked Questions (FAQ) template, which has a FAQ section. Each FAQ section might have any number of FAQ Blocks, which have a text setting for the ‘Question’ and ‘Answer’ respectively. This was a great foundation for simple use cases, but more complicated use cases start to fall apart quickly.
Developers would quickly hit limitations with section blocks. The first iteration of blocks were not shared between sections, so it meant creating lots of little snippets for small things like a ‘Heading’ or ‘Button’ if you wanted to ensure your markup was consistent. At the same time, the Shopify editor would actually prevent you from nesting snippets too deeply, so developers were encouraged to think of reusable code as an antipattern rather than a sign of a well designed system.
Merchants would also suffer too. If we take our FAQ example, if a merchant wanted to add a video to the FAQ answer, they would not be able to do so using the included richtext setting, as it only allows for a small subset of formatting related HTML.
There were some workarounds, with developers implementing the ability to draw from a page instead of a richtext field, but the merchant editing experience was still subpar. This setup would require the merchant to be able to switch to the HTML mode in the WYSIWYG editor, and they would need to create a new page for every FAQ question. This meant that the platform felt more convoluted than it needed to be, and it was often difficult for merchants to understand why what felt like a simple task in other website builders was so difficult in Shopify.
Theme blocks changed all that.
Now, sections can have blocks, which have up to 8 nested levels of blocks. Furthermore, a set of global theme blocks can be defined, so a section can have access to all your typical primitives with a single line of code: {% content_for 'blocks' %}. This lets you choose between any block allowed by the developer in that section, including all global theme blocks.
In addition to those blocks, there is the option to utilize static blocks, which can be slotted into specific places in a section. For example, a slideshow section may have any number of slide blocks, but only one pagination block slotted in a fixed spot in the markup. You wouldn’t be able to add extra slideshow pagination blocks, but the ability to pull it out as a block means that you can add settings to the pagination that will apply across all slideshow sections in your theme.
Why use theme blocks?
At Ultramarina, we were absolutely delighted to see Shopify roll out these theme blocks, as it felt like an embrace of the designs system thinking that allows businesses to scale while still maintaining clean code and a coherent visual identity.
When theme blocks had launched, we were actually nearly done with the version of the theme that utilized the previous Online Store 2.0 (OS 2.0) architecture – we were near the end of the review process and could have launched imminently.
We made the bold move to rewrite the whole theme using theme blocks architecture, even though Shopify hadn’t yet provided opinionated guidance on implementation patterns. Being early adopters meant navigating uncharted territory and making our own decisions about the optimal way to structure certain features. As we see it, there are several advantages for this new theme blocks architecture that made this pioneering effort worthwhile, and we’ve since been commended by other theme partners on our approach.
New levels of design customization
We’ve already given several examples of this earlier, but this really is the number one benefit behind theme blocks. Before, even something as simple as adding a secondary call-to-action (CTA) inline with the first meant that a theme developer had to anticipate that need and provide separate settings, ie. ‘Button Text 1’, ‘Button Link 1’, ‘Button Text 2’, ‘Button Link 2’. It was really hard to strike the right balance between giving merchants what they want without overburdening the settings.
Now, you have a ‘Button Group’, where merchants can add as many buttons as they need without being overwhelmed by too many unused settings.
Easier codebase maintenance
Theme blocks don’t have the nesting limits that snippets do. We were able to iron out a lot of consistency-related issues and bugs by reducing one-offs and de-duplicating code. Our previous codebase had a lot of areas where had copy and pasted markup from one place to another in order to not surpass the nested snippet limit. But as we changed things and added new features, it was possible for code to fall out of sync, causing visual inconsistencies between sections.
While there are definitely issues with over-abstraction, we believe that theme blocks strike the perfect balance, creating DRY-er (Don’t Repeat Yourself), more modular codebases.
It cuts down on the effort required by third-party developers
From my experience working on merchant stores, it was often difficult to communicate why certain things would take more time. For example, say you had a section like this, what we call a Split Card in Primavera.
One merchant wanted to add a star rating to this section, which would show star icons next to a line of text that had the review count. With OS 2.0 architecture, a merchant’s developer might edit this section to add the settings directly. If they were thinking ahead, maybe they would have added the markup as a snippet, so it could be reused across the theme. But still, if the merchant wished to reuse to use this star rating component across the site, they’d have to add it to every section that needed it, copy and pasting those settings into those sections.
If the theme developer then updated the theme, there is a potential for merge conflicts in every single file that the merchant’s developer has touched. Many merchants never update their premium Shopify themes, missing out on new features and performance enhancements, just because migrating would be too difficult.
With theme blocks, a developer would simply need to add a single file, a blocks/star-rating.liquid file. When it’s time to update, there would be no merge conflicts at all as the original theme code and the custom code remains partitioned. Developers and merchants can spend less time fighting the platform and code, and more time on strategizing and implementing larger features.
Better third-party integrations
One thing we notice a lot on e-commerce stores is how piecemeal they can tend to look, especially ones that use many third-party apps. Unless a developer spent a lot of time bringing app styles close to the existing brand, there’s often a sense of disjointedness, with app content living in separate sections.
With theme blocks, app blocks can more easily coexist with brand content and create more immersive experiences. For example, you could have a shipping rates calculator app block within an accordion block within your product page, along with your store specific content. With theme blocks architecture, the possibilities are endless, and I’m excited to see what creative ways people find to create a more cohesive store experience.
Future-proofed for Shopify’s new features
At the time of writing, Primavera is the only premium theme in the Theme Store built entirely on Shopify’s new theme blocks architecture. When Shopify surprise-launched AI-generated blocks at Summer Editions 2025, Primavera also became the only premium theme that supported the new AI-generated blocks from day one – no modifications or workarounds needed. Although there were significant risks with launching with a new, untested architecture, we think we’re only beginning to see the full potential of a block-based architecture, and we’re excited to see what’s next.
How should theme blocks be implemented?
When we were implementing theme blocks, there weren’t any prior examples of themes that we could reference. From our past experience working with other site builders, we knew that merchants could easily be overwhelmed by too many levels of nesting. We chose to forgo generic wrapper blocks, even if it meant losing some flexibility, if it meant for a smoother merchant experience. Since our experience was more of a retrofit than a greenfield project, the code was already completed, we just needed to figure out where each bit of code should live.
We also focused on exposing global theme blocks only where they made the most sense, such as rich text sections and other areas where merchants need dynamic content flexibility. In order for a block to be considered a global theme block, we had to come up with a valid use case for it in more than two sections. In the end, we had a collection of super flexible global theme blocks, as well as a selection of carefully curated hidden theme blocks to be paired with their relevant sections.
Are there any limitations to theme blocks?
Not everything about the theme blocks rollout has been ideal. The Shopify theme development community has given plenty of feedback along the way, but unfortunately, the traditional section blocks code and theme blocks code have slight differences that can make certain patterns challenging.
The markup is ‘as is’
Take this snippet, it’s similar to what you might find in many slideshows or carousel patterns. In the code below, we loop through the section blocks, and if the block type is ‘slide’, then we output a slide wrapper element and render a media banner within it.
{%- for block in section.blocks -%}
{% if block.type == 'slide' %}
<div role="group" aria-label="{{ forloop.index }} {{ 'general.slider.of' | t }} {{ forloop.length }}">
{% render 'image-banner' with settings: block.settings %}
</div>
{% endif %}
{%- endfor -%}In the new architecture you can only output theme blocks with {% content_for 'blocks' %}. You can’t filter on the block type, you can’t put different blocks in different parts, and you can’t add a wrapping element. While all blocks have access to the section liquid object, this section object doesn’t expose the section type.
As a result, if you had an image banner block and you wanted to use it as a slide in a slideshow, you would need to make a separate, slideshow-specific block in order to wrap that slide item wrapping element around it.
There are ways to structure you sections and blocks around this limitation, but it does feel like it makes the migration less smooth than it should be when you can’t just rely on old markup patterns.
Unable to pass parameters in
The shopify render tag is a way of including repeated blocks of markup, and it allows you to pass in variables to the code inside. This is wonderful, and is a vital tool in all themes. However, blocks don’t let you pass parameters into them, which meant that we had to implement several blocks that just render a snippet with different parameters.
Again, there are ways to work around it, but we think those coming from a JavaScript framework would be horrified at the idea of components without parameters.
Section blocks and theme blocks are mutually exclusive
Shopify code is backwards compatible, you can still run stores on the old theme architecture even before OS2.0. However, this comes with the tradeoff where you cannot use global theme blocks in sections with traditional section blocks. This doesn’t affect new themes such as Primavera that much, but it makes it impossible for theme developers of OS 2.0 themes to gracefully add new theme blocks in.
No block limits
There’s no way to set a limit to how many times a block appears in a section. This is particularly problematic for places like the product page, where you could theoretically have multiple variant picker blocks, possibly leading to broken behaviors with duplicate form IDs and other similar issues. Thankfully, we’ve not yet come across any merchants who have done something like this, but we would love the ability to implement proper guardrails to ensure a working experience.
Closing thoughts
We hope this post has convinced you that theme blocks are the way forward for the Shopify ecosystem. Between our two founders, we have well over a decades worth of experience with the Shopify ecosystem, and we think this is one of the most exciting updates Shopify has ever shipped!
If you want to preview Primavera, you can try it via the Theme Store. If you’re an agency looking to speed up your next build with Primavera, feel free to reach out for more information.
