Inline Snippets

[karreiro]

Author: Shopify
Expected end date: March 21st, 2025

Background

Liquid templates can often become quite verbose, with snippets serving as the primary method for reusing code.

Developers frequently need to choose between creating many separate files in a "snippets" directory or managing large and complex Liquid templates. This dilemma can lead to complicated templates and duplication.

For example, when working on a product.liquid section, developers frequently break it down into:

• snippets/product-header.liquid
• snippets/product-accordion.liquid
• snippets/product-content.liquid
• snippets/product-media-modal.liquid
• snippets/product-media.liquid
• snippets/product-thumbnail.liquid

This approach can clutter the snippets directory with files that are only relevant to a specific template, making the codebase less cohesive, harder to maintain, and to organize, especially as it grows.

Proposal

We propose introducing inline snippets—a feature that allows developers to define and reuse code within the same file. This eliminates the need for additional snippet files when the code is only relevant within a specific context.

Consider the following snippets/nav.liquid file:

{% snippet header %}
  <h1>{{ title }}</h1>
  {% if search %}
    <div class="nav-search">
      <input type="text" placeholder="Search...">
    </div>
  {% endif %}
{% endsnippet %}

<div class="nav-header">
  {% render header, title: "Main menu", search: true %}
</div>

<div class="nav-header--mobile">
  {% render header, title: "Main menu" %}
</div>

Nested inline snippets

Inline snippets can also be nested and accessed externally, allowing developers to group related snippets into cohesive modules. Here's the updated snippets/nav.liquid file:

{% snippet header %}
  <div class="nav-header">
    <h1>{{ title }}</h1>
    {% if search %}
      <div class="nav-search">
        <input type="text" placeholder="Search...">
      </div>
    {% endif %}
  </div>
{% endsnippet %}

{% snippet tabs %}
  {% snippet tab %}
    <li>
      <a href="#tab{{ id }}" {% if active %}class="active"{% endif %}>
        Tab {{ id }}
      </a>
    </li>
  {% endsnippet %}

  <div>
    <ul>
      {% render tab, id: 1, active: true %}
      {% render tab, id: 2 %}
      {% render tab, id: 3 %}
    </ul>
  </div>
{% endsnippet %}

{% render header, title: "Main menu", search: true %}
{% render tabs %}

The header, tabs, and tab snippets are defined within the file. Notice that the tab snippet is accessed using dot notation since it's nested within tabs:

{% render tabs %}
{% render tabs.tab, id: 4 %}

The snippets/nav.liquid file can still be rendered entirely or have only a specific snippet within it rendered (for example, "nav.header"):

{% render "nav" %}
{% render "nav.header", title: "Sub menu", search: false %}

By grouping related snippets under a common namespace, developers can organize related snippets together and reduce the number of files.

Call for suggestions

We welcome any feedback or opinions on this proposal. Please share your thoughts by March 21st, 2025. Your input is valuable as we prepare to begin active development on this initiative.

[jg-rp]

Array of arguments

I like the idea of exposing render tag arguments as an array inside snippets, a bit like Jinja does with call/macro. If we were to call said array arguments, like in JavaScript, snippets could loop over the arguments without needing to know how many there are or what they are called.

{% snippet tabs %}
  {% snippet tab %}
    <li>
      <a href="#tab-{{ name }}">
        Tab {{ value }}
      </a>
    </li>
  {% endsnippet %}

  <div>
    <ul>
      {% for argument in arguments %}
        {% render tab, name: argument[0], value: argument[1] %}
      {% endfor %}
    </ul>
  </div>
{% endsnippet %}

{% render "tabs", blog: 'some blog', page: 'some page' %}

There is a risk that arguments (or whatever other name is chosen) conflicts with arguments to render tags in existing templates.

Changing the render tag to accept positional arguments as well as named/keyword arguments might be useful too, but then we'd need to reserve names for two arrays, like args and kwargs.

[t-kelly]

👋🏻

1. {% render %} would support variables?

{% render tabs %}
{% render tabs.tab, id: 4 %}   

Render currently only supports a string as an input, does this proposal include expanding accepted inputs to variables? Or is the proposal limiting variables to just inline snippet declarations?

2. Use-cases for using parent + nested snippets?

Interesting part of the proposal! Do you have any real-world examples in mind of where both the parent and nested outputs would be used?

Drawing a lot of similarities to JS module default vs named exports. Could be cool to have a utils.liquid filled with nested snippets that help with a variety of operations like {% render 'utils.image_sizes' %}. Wouldn't see the need in that case to have a parent/default export from {% render 'utils' %}

3. Would the new {% docs %} tag be supported within inline snippet declaration?

In the above utils example, it would definitely be useful to define params and examples for each inline snippet. In other cases it could lead to a really gross looking file with {% docs %} declarations scattered everywhere

[zacariec]

I think this is a great idea - but I wonder if {% snippet %} is the right place for it.
I wonder if making {% capture %} support arguments is a good approach or maybe {% snippet %} is the way forward afterall.

{% capture header %}
  <h1>{{ title }}</h1>
  {% if search %}
    <div class="nav-search">
      <input type="text" placeholder="Search...">
    </div>
  {% endif %}
{% endcapture %}

<div class="nav-header">
  {{ header | args: title: "Main menu", search: true }}
</div>

<div class="nav-header--mobile">
    {{ header | args: title: "Main menu" }}
</div>

[PaulNewton]

I completely missed and only noticed it through it getting merged? #2001
Similar to @zacariec I don't think {% snippet %} is appropriate not because of exisitng tags but for end user pedagogy of liquid.

@karreiro the ship may have sail but if there's a time to rename this please consider doing so
On platforms like shopify liquid isn't meant solely for developers, merchants need to be able to wrap thier heads around things too.
So currently the logic merchants have to adopt is like this:
themes have templates but everything is a template when talking about anything snippets are templates but they have to be rendered or included in other templates though sometimes sections but sections are templates too though they aren't in the /templates folder.
And that's just confusion about talking about files before moving to tags etc.

Now add a {% snippet %} TAG to the mix when talking about snippets.
"Just go into the price snippet and comment out the compare_at_price lines"
In that sentence what am I talking about? A file or a tag

This type of overloading ambiguity in words/concepts adds a lot of friction.
It's right up there with "scripts" for plus plans on shopify being useable for checkout never getting a proper defined name/concept so there was constant assumptions of that meaning javascript was expected to be useable when it was just ruby.

[oreoorbitz]

I think the issues on naming come from the common issue of being trapped backwards compatibility while torturing the users of your language with outdated syntax.

From my personal expierence, the I think the most pure liquid logic i've written (all inside a single {% liquid %} tag was about 500 lines. mostly because of the need for many diferent predicates (lambdas plz). So for really complex liquid logic, i'd probably end up using seperate files anyways. Yes we need safer scope management, this is 2026, but capture with block scoping isn't really that helpfull for most developers doing complex things with liquid.

What I most desperately want, and I think many other devs desperately want, is way to create factories to populate the scope. We have capture for modualizing html output, Liquid developers are used to degenerate mutability, introducing a new tag for better scope controll but keeping capture as is, is like putting a single door in the facebook offices and telling people to respect privacy more. Complex liquid code becomes incredibly verbose, I think we mostly want ways to make it less verbose. So if you're not scared about becoming PHP, give us functions. Though I realize that's a whole can of worms you probably don't want to open.

If you want to keep to being a templating language, update existing tags in non destructive ways for better developer ergonomics. Implement the update to render so it accepts variables as arguements like you did in the PR you reverted. Add arguement shorthand for render calls. Somethings might be too destructive to do now, like updating capture for scoped variables, but you can use your strict parsing updates to force people to gradually move away from affecting the scope within capture, so that you can eventually make capture safer. Scare merchants into paying us developers to update their ancient themes like you did with the scss deprecation and the webcore vitals dashboard.

Tldr,
The naming is confusing because Shopify knows theme develoeprs desperately need more scope saftey, but can't safely update the existing features to add scope saftey without another long drawn out ´include -> render´ like process, and that results in syntax confusion.

[PaulNewton]

Onboard with everything but "Scare merchants into paying us developers" as those examples of migrations the platform should automate and deprecations of things they shouldn't really have been doing in the first place and were shims to excuse not doing the right thing.
ala {% includes %} in the assets files/directory, and dumping merchants into a dashboard with no education to push a mentality of score-must-go-up creating an entire cottage industry of scammers.

[jg-rp]

How about {% define some_name %}...{% enddefine %} instead of {% snippet some_name %}...{% endsnippet %}?

Just like {% capture %} describes what you're doing - "rendering a block of Liquid markup and saving the result for later" - {% define %} says "save this parameterized block of Liquid markup for later, without rendering it".

This feels more consistent to me. Both tag names are actions, neither are trying to describe what the block is, like "this is a snippet".

A {% define %} block is still conceptually and inline snippet, but you are free to describe it without using the overloaded term "snippet".

Scope

{% capture %} has "template scope". Captured blocks have access to all "global" variables and any variables assigned with preceding assign, capture, increment and decrement tags.

{% define %} has "block scope". Defined blocks have access to global variables, their arguments, and local assigns etc. only.

Note

Adding parameters/arguments to {% capture %} is a separate issue, in my opinion. Differing behaviour and scoping rules alone mean we should not overload {% capture %} with inline snippet semantics. There's also no obvious syntactic way to differentiate between "render and capture" vs "save without render".

Snippet namespace/register

I believe blocks defined with {% define %} should have their own namespace (aka register). This would make it impossible to assign a block to another variable or pass a block to {% render %} or {% include %}, things the previous implementation did allow.

Sticking with {% render "some_name" %} for rendering snippet files AND inline snippets (both with quotes), the render tag would first look in the "snippets" register (edit: you could just shove inline snippets into the existing:cached_partials register, maybe), then fall back to the filesystem/database. This makes it possible for inline snippets to "shadow" file-based snippets.

[PaulNewton]

define is pretty good, avoids talking about functions,macros or implying them.

no obvious syntactic way to differentiate between "render and capture" vs "save without render".
At least til it's label is called.

[sdn90]

I'm happy with the approach in the OP.

There's been ideas that have been passed on over the years related to code reuse. The Shopify team's argument has been that it adds complexity for merchants.

Has anything changed on this? (FWIW I've always been against that stance and believe this is a big net benefit)

[PaulNewton]

Some merchants have problems even finding the code editor itself, or working in it and that was before the VScode complexity explosion.

The tabs example in the OP is incredibly confusing to the uninitiated ; borderline like recursion stuff that would confuse compsci first-years.

This would confuse even somewhat savvy merchants simply from the names being slightly different.

{% snippet header %}
  <h1>{{ title }}</h1>
  {% if search %}
    <div class="nav-search">
      <input type="text" placeholder="Search...">
    </div>
  {% endif %}
{% endsnippet %}

...
{% capture heading %}
<h{{section.setting.heading_level}}> {{ page.title }} </h{{section.setting.heading_level}}>
{% endcapture %}}

...

<div class="nav-header">
  {{ heading }}
</div>

<div class="nav-header--mobile">
  {% render header, title: "Main menu" %}
</div>

And is the stuff that will happen