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.