Snippets

Snippets are reusable fragments of Liquid. They hold markup and logic that is used in more than one place, or that is large enough to be worth pulling out of a section or layout.

Reach for a snippet when the same markup appears in more than one section, or when a single piece of a section has grown large enough to obscure the rest of the file. A snippet has no schema and no settings of its own; it renders whatever it's given.

Location

Snippets live in the snippets directory of the theme, one .liquid file per snippet.

└── theme
    ├── layout
    ├── sections
    ├── snippets
    │   ├── _config.liquid
    │   ├── block.slide.liquid
    │   ├── misc.icon.liquid
    │   ├── product-price.liquid
    │   ...
    ...

A snippet is referenced by its file name without the extension. The directory is flat, so themes commonly namespace file names with a dot prefix to group related snippets:

Prefix	Used for
_	Partials wired into the layout, such as _config and _meta-tags.
block.	Markup for a single block type, such as block.slide.
core.	Storefront building blocks, such as core.cart-item and core.variants.
misc.	Small shared pieces, such as misc.icon and misc.pagination.

The prefixes are a convention, not a requirement.

How to use snippets

Render a snippet with the {% render %} tag.

{% render 'product-price' %}

Passing variables

A snippet can read the theme's global objects (settings, store, product, and so on) and any variable that's in scope where the snippet is rendered, including the current {% for %} loop variable. Pass anything else it needs as a named parameter:

{% render 'product-price', product: featured_product, show_compare_at: true %}

{%- comment -%} snippets/product-price.liquid {%- endcomment -%}
<span class="price">{{ product.price | money }}</span>
{% if show_compare_at and product.compare_at_price > product.price %}
  <s class="price-compare">{{ product.compare_at_price | money }}</s>
{% endif %}

Variables created with {% assign %} inside a snippet stay local to that snippet.

with and for

Use with to pass a single object under a chosen name, and for to render the snippet once per item in an array:

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

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

See the render tag reference for the full syntax.

Note: {% include %} is not supported. Use {% render %}.

Documenting snippets with LiquidDoc

Document a snippet's interface in a LiquidDoc comment at the top of the file. It's written inside a {% comment %} block, so it never reaches the rendered output, and it gives anyone calling the snippet a single place to see what it expects.

{% comment %}
  @description
  Renders a product price, with an optional struck-through compare-at price.

  @param {object} product - The product to price.
  @param {boolean} [show_compare_at] - Show the compare-at price when it's higher. Defaults to false.

  @example
  {% render 'product-price', product: featured_product, show_compare_at: true %}
{% endcomment %}

Tags

Tag	Purpose
@description	What the snippet renders, in one or two lines.
@param {type} name - description	One per input the snippet reads. Wrap the name in [brackets] when it's optional.
@example	A representative {% render %} call.

Common @param types are string, number, boolean, object, and array.

Example

{% comment %}
  @description
  Renders a single slide. Reads the current block from the enclosing
  `{% for slide in section.blocks %}` loop.

  @param {object} slide - The slide block, supplied by the loop variable.

  @example
  {% for slide in section.blocks %}
    {% render 'block.slide' %}
  {% endfor %}
{% endcomment %}

<li ui-block="slide" {{ slide.youcan_attributes }}>
  <h2>{{ slide.settings.heading }}</h2>
  <p>{{ slide.settings.text }}</p>
</li>