Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 61 ยท Liquid Basics

Snippets and the render Tag

Learn how Shopify snippets work: the render tag, passing variables, isolated scope, render with and for, why include is deprecated, LiquidDoc comments and nesting limits.

A snippet is a small, reusable piece of Liquid that lives in the snippets/ folder of your theme. A product card, a price line, an icon, a badge: anything you would otherwise copy and paste into three different sections belongs in a snippet. When the markup for a price changes, you edit one file instead of hunting down every copy.

You call a snippet with the render tag. It looks like a function call, and that is the right way to think about it: you hand the snippet some inputs, it produces some HTML, and it cannot reach back into the code that called it. This lesson explains exactly what a snippet can and cannot see, how to pass data in, why the older include tag is deprecated, how to document snippet arguments, and where the limits are.

What this lesson targets: Online Store 2.0 themes and current Shopify Liquid (the render tag and the {% doc %} LiquidDoc tag). The real Liquid code in the plain code blocks cannot run on this site, because there is no Shopify here. The editors do run a small Liquid-style engine written in JavaScript, which is a stand-in: it implements render, include, if, for, assign and a few filters so you can watch the scoping rules happen. It is not Shopify's Liquid, and it leaves out most of the real filter library.

A first snippet

A snippet is a plain file with Liquid and HTML. It has no {% schema %} block, so it never shows up in the theme editor by itself. Here is a snippet that formats a price:

LIQUID
{%- comment -%} snippets/price.liquid {%- endcomment -%}
<span class="price">
  {{ price | money }}
</span>

And here is how a section uses it:

LIQUID
{% render 'price', price: product.price %}

Three things to notice. The snippet name is a quoted string without the folder or the .liquid ending. After the name comes a comma, then name: value pairs; each pair becomes a variable inside the snippet. And the name has to be a literal string: you cannot write {% render snippet_name %}. Shopify wants to know which files a template depends on without running it, so Liquid refuses a variable there with a syntax error.

Passing data in

You can pass anything: strings, numbers, booleans, objects, arrays, the result of a filter chain.

LIQUID
{% render 'product-card',
  product: product,
  show_vendor: true,
  image_width: 480,
  badge: 'New' | upcase
%}

Passing an object does not copy it. The snippet receives the same product, so there is no cost penalty for handing over a big object.

There are two shorthand forms for the common case of "render this snippet for one thing, or for each thing in a list":

LIQUID
{% render 'product-card' with featured_product as product %}

{% render 'product-card' for collection.products as product %}

The with form passes one value under the name after as. The for form renders the snippet once per item and gives each run a forloop object, just like a for tag. If you leave out as, the variable gets the snippet's own name, so {% render 'product' with featured_product %} creates a variable called product inside snippets/product.liquid. You can add extra name: value pairs after either form.

Isolated scope

This is the single most important rule: a rendered snippet has its own scope. It starts empty except for the arguments you passed and the global objects. Variables you created with assign or capture in the calling template are invisible inside. Variables the snippet creates are thrown away when it finishes.

flowchart LR
  A["Calling section<br/>assign sale = true<br/>product, section, block"] -->|"render 'card', product: product"| B["Snippet scope"]
  G["Global objects<br/>shop, settings, request,<br/>routes, cart, localization"] --> B
  B -->|"returns HTML only"| A

A snippet sees the arguments you pass plus the global objects. Nothing it assigns flows back to the caller.

Which objects are global? The ones documented as available everywhere, such as shop, settings, request, routes, cart, customer and localization (lesson The Global Objects You Use Most lists them). Objects that belong to a particular section, namely section and block, are not something to count on inside a snippet. If a snippet needs the section id or a block, pass them explicitly: {% render 'slide', block: block, section_id: section.id %}. Being explicit also makes the snippet testable: you can read its inputs from its first lines.

The isolation is a feature. A snippet that reads a variable it did not receive is silently coupled to every template that calls it, and one rename breaks it somewhere far away. Isolation forces that coupling to be visible in the render call.

Why include is deprecated

Before render there was include. It runs the snippet in the caller's scope: the snippet can read every variable of the caller, and every assign inside it overwrites the caller's variables.

LIQUID
{% assign size = 'large' %}
{% include 'tile' %}
{{ size }}

If tile.liquid itself contains {% assign size = 'small' %}, the last line prints small, not large. That is the bug factory. Snippets quietly depended on, and changed, variables elsewhere. Shopify deprecated include and Theme Check flags it. Use render everywhere. If you open an older theme that still has include, migrate each call by listing the variables the snippet actually reads as arguments. As an additional guard, Shopify does not allow include inside a snippet that was rendered with render (you get a Liquid error instead), so you cannot slip back by accident.

Run the first editor and compare the two tags. The render snippet cannot see outer and its assign does not leak; the include shares everything.

JS render versus include in a mini Liquid engine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line of output shows a snippet that renders itself forever. The stand-in stops at a depth of 5 and prints an error. Real Liquid also guards against runaway nesting and reports a "Nesting too deep" error when you go too far; the exact limit is Shopify's business, so do not build designs that depend on deep recursion.

A grid with render for and defaults

Most of the time you will render a snippet inside a loop and give optional arguments a default. Since a snippet cannot assume that the caller passed everything, the first lines of a snippet usually normalize the inputs:

LIQUID
{%- comment -%} snippets/product-tile.liquid {%- endcomment -%}
{%- liquid
  assign size = size | default: 'medium'
  assign show_price = show_price | default: true, allow_false: true
-%}
<article class="tile tile--{{ size }}">
  <h3>{{ product.title | escape }}</h3>
  {% if show_price %}
    {% render 'price', price: product.price %}
  {% endif %}
</article>

Look at allow_false: true. The plain default filter replaces nil, false and empty strings. So show_price | default: true turns an explicit false back into true, and a caller can never switch the price off. Adding allow_false: true tells default to keep a real false. This is one of the most common snippet bugs, and the next lesson on pitfalls comes back to it.

The call site for a whole grid is one line:

LIQUID
{% render 'product-tile' for collection.products as product, size: 'small', show_price: false %}

Every product runs the snippet once, forloop.index works inside it, and size and show_price are the same for every run.

Documenting arguments with LiquidDoc

A snippet is a function without a signature, so how does the next developer know which arguments it wants? You write a {% doc %} block at the top. Everything inside a doc tag is ignored by Liquid at render time, so it costs nothing, but the code editor and Theme Check can read it to autocomplete arguments and warn about missing or unknown ones.

LIQUID
{% doc %}
  Renders one product tile.

  @param {object} product - The product to show
  @param {string} [size] - 'small' or 'medium' (default)
  @param {boolean} [show_price] - Show the price line

  @example
  {% render 'product-tile', product: product, size: 'small' %}
{% enddoc %}

The syntax is a @param line with a type in curly braces, the argument name, a dash and a description. Square brackets around the name mark the argument as optional; without them it is required. @example blocks show a sample call. Types are the simple ones such as string, number, boolean and object. Treat the exact list of supported tags and types as something to check in the current Shopify documentation, because LiquidDoc is still growing.

You can see how a checker like that works. The editor below parses the @param lines of a doc block and validates calls against them. This is again a stand-in for what Theme Check does, written in plain JavaScript.

JS A LiquidDoc argument checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reuse without overdoing it

Snippets are cheap to write, so it is tempting to turn every <div> into one. A few guidelines keep that from becoming a maze:

  • Snippet when it repeats or has one clear job. A price, a product card, an icon, a pagination control. If you have used the same 20 lines three times, extract them.
  • Section when merchants should configure it. A snippet cannot have a schema. Anything the merchant should edit in the theme editor belongs to a section or block (Building a Section).
  • Name snippets by what they are, in lowercase with hyphens: price, product-card, icon-cart. Group related ones with a prefix such as icon- or card-.
  • Keep the argument list short. Six or more arguments often mean the snippet is doing two jobs, or that you should pass one object (product) and let it read what it needs.

On performance: a render call is much cheaper than the old include, because the snippet is compiled once and scope handling is simple. Still, every call has a cost. A snippet rendered inside a loop of 50 products, which itself renders another snippet per variant, multiplies quickly. Measure before you worry, and keep loops inside snippets shallow. The lesson on Liquid Performance shows how to measure with Shopify's theme profiler.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A section does {% assign badge = 'Sale' %} and then {% render 'card', product: product %}. Can snippets/card.liquid print {{ badge }}?

    render gives the snippet an isolated scope. To use badge, pass it as an argument, for example badge: badge.
  2. 2. Which call is valid Liquid?

    The snippet name must be a quoted string literal without folder or extension, followed by optional name: value pairs.
  3. 3. Why is include deprecated?

    Shared scope makes snippets depend on hidden variables and change them behind your back. render makes all inputs explicit.
  4. 4. A snippet receives show_price and uses assign show_price = show_price | default: true. A caller passes show_price: false. What does the snippet get?

    The default filter treats nil, false and empty strings as missing. Use default: true, allow_false: true to keep a real false.

Summary

  • A snippet is a reusable Liquid file in snippets/, called with {% render 'name', arg: value %}; the name must be a quoted literal.
  • render gives the snippet an isolated scope: it sees only the arguments you pass plus global objects, and nothing it assigns leaks out. Pass section and block explicitly when you need them.
  • with ... as renders once with one value; for ... as renders once per item and provides forloop.
  • include shares scope with the caller, is deprecated, and should be replaced by render with explicit arguments.
  • Normalize optional arguments at the top of a snippet, and use allow_false: true when false is a valid value.
  • Document arguments with a {% doc %} LiquidDoc block so editors and Theme Check can validate calls.
  • Nesting depth is limited, so do not design around recursion, and keep render-in-loop chains shallow.

Next lesson: Liquid Pitfalls and Debugging.