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