Shopify Essentials: Liquid template fundamentals

The parts of Shopify's Liquid templating language you'll use on every theme: output and logic tags, objects, filters, loops, snippets and the usual mistakes.

Updated 3 min read

Liquid is the templating language behind every Shopify theme. It puts store data such as products, collections and the cart into HTML, with {{ }} to print a value and {% %} for logic. This guide covers the parts you’ll use on every theme: output, logic, objects, filters, loops and snippets, then the common mistakes.

What is Liquid?

Shopify created Liquid and released it as open source. It runs on Shopify’s servers, so the browser receives finished HTML with the store’s data already in it.

Basic syntax

A value to print goes in double braces, {{ ... }}. Logic goes in tags, {% ... %}.

Output

{{ product.title }}

Logic

{% if product.available %}
  In stock
{% else %}
  Sold out
{% endif %}

Objects

Objects hold the store’s data. The ones you’ll use most are:

  • product
  • collection
  • cart
  • shop
  • settings

Read a property with a dot, and pass it through a filter to format it:

{{ product.price | money }}

Filters

Filters change a value before it’s printed:

{{ product.title | upcase }}
{{ product.description | strip_html | truncatewords: 20 }}

Product descriptions contain HTML, so strip the tags before truncating. Otherwise you can cut a tag in half and break the layout.

Filters chain from left to right:

{{ shop.name | downcase | replace: " ", "-" }}

Loops

A for loop goes through each item in a list:

{% for product in collection.products %}
  {{ product.title }}
{% endfor %}

limit, offset and reversed control which items it covers:

{% for item in cart.items limit: 3 %} ... {% endfor %}

Snippets

{% render %} drops a snippet into the template. Pass in the variables it needs:

{% render 'product-card', product: product %}

Shopify has deprecated {% include %}, so use render in new code. A rendered snippet can’t see the template’s variables unless you pass them in, which keeps it predictable.

Variables and settings

  • assign: create a variable
  • capture: build a string from a block of markup
  • cycle: rotate through values, such as alternating row colours
  • section.settings: read the settings defined in a section’s schema
{% assign sale = true %}
{% if sale %} <div>On Sale</div> {% endif %}

Common mistakes

  • Printing an object instead of one of its properties: {{ collection.title }}, rather than {{ collection }}
  • Running logic inside a loop when it could run once before it
  • Nesting snippets inside snippets until nobody can follow the render chain

Habits that keep a theme easy to work on

  • Keep templates shallow, and move repeated markup into a snippet
  • Put the text and options a merchant should change in section.settings
  • Profile slow loops with Shopify Theme Inspector before changing them
  • Name variables for what they hold
  • Comment any logic that isn’t obvious from the code

I write Liquid like this when I build a custom Shopify theme for a retailer, or take over one they already have.

Published , updated .

Part 3 of Shopify Essentials.

Related posts