LiquidLiquid Basics

Liquid Basics

Liquid is a small template language: plain HTML with two kinds of markers in it. Double braces print a value, braces with percent signs run logic. This page covers the whole language with examples you can edit and run.

Output and filters

{{ … }} prints a value. A pipe passes it through a filter, which changes it: formats money, resizes an image, shortens text. Filters chain left to right, and some take arguments after a colon.

Outputliquid
<h2>{{ product.title }}</h2>
<p>{{ product.price | money }}</p>
<p>{{ product.title | upcase | truncate: 12 }}</p>
<p>{{ product.vendor | default: "No brand" }}</p>

An object that does not exist prints nothing rather than failing, so {{ product.title }} on a homepage prints an empty string. A filter that does not exist is an error: the section will not save. The full list is on Filters.

Conditions

if, elsif, else and unless (the opposite of if) branch on a value. case picks between fixed values.

Conditionsliquid
{%- if product.on_sale -%}
<span class="badge">Sale: save {{ product.compare_at_price | minus: product.price | money }}</span>
{%- elsif product.tags contains "new" -%}
<span class="badge">New in</span>
{%- else -%}
<span class="badge">Classic</span>
{%- endif -%}
{% unless product.available %}<p>Sold out</p>{% endunless %}
{% case product.type %}
{% when "Shirts", "Tops" %}<p>See the size guide.</p>
{% when "Mugs" %}<p>Dishwasher safe.</p>
{% else %}<p>{{ product.type }}</p>
{% endcase %}
OperatorMeaning
== · !=Equal, not equal
> · < · >= · <=Greater, less
and · orBoth, either. Evaluated right to left, and there are no parentheses: nest ifs instead.
containsA string contains a substring, or an array contains a string: product.tags contains "sale"
blank · emptyproduct.vendor == blank is true for nil, false, "" and empty arrays

What counts as true

Only nil and false are false. An empty string, 0 and an empty array are all true, which surprises people coming from JavaScript. Test emptiness explicitly:

TruthinessSample store data
true

Loops

for repeats over an array or a range. Inside it, forloop tells you where you are. {% else %} runs when the array is empty, which is the cleanest way to write an empty state.

Loops
Playground
Loading editor…

Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.

forloop.Value
index · index0Position from 1 / from 0
rindex · rindex0Position from the end
first · lasttrue on the first / last pass
lengthHow many passes in total
parentloopThe enclosing loop’s forloop, in a nested loop

for takes limit:, offset: and reversed. {% break %} leaves the loop and {% continue %} skips to the next pass. {% cycle "a", "b" %} alternates values between passes.

Variables

assign stores a value, capture stores rendered text. {% liquid %} lets you write several tags in one block, one per line, with echo for output.

Variablesliquid
{%- assign uid = section.id | default: "demo" -%}
{%- assign cheapest = products | sort: "price" | first -%}
{%- capture headline -%}
{{ products.size }} products from {{ cheapest.price | money }}
{%- endcapture -%}
<h3 id="title-{{ uid }}">{{ headline }}</h3>
<p>Cheapest: {{ cheapest.title }}</p>
{%- liquid
assign on_sale = products | where: "on_sale", true
echo "<p>On sale: " | append: on_sale.size | append: "</p>"
-%}

Build keys before you use them in brackets

Filters do not run inside brackets. s['slide_' | append: i] silently reads nothing. Assign the key first, then look it up: {% assign key = 'slide_' | append: i %}{{ s[key] }}. This is the most common bug in submitted sections; see Authoring standards.

Whitespace control

A hyphen inside a delimiter ({%-, -%}, {{-, -}}) strips the whitespace on that side. It keeps the HTML tidy and matters inside attributes and inline text, where a stray newline becomes a visible space. Compare the two outputs in the HTML tab:

Whitespaceliquid
<p>
{% for tag in product.tags %}
[{{ tag }}]
{% endfor %}
</p>
<p>
{%- for tag in product.tags -%}
[{{ tag }}]
{%- endfor -%}
</p>

Comments and raw

{% comment %}…{% endcomment %} and the inline {% # note %} are never rendered. {% raw %}…{% endraw %} prints Liquid syntax as text, for when you need literal braces.

Strings, numbers and arrays

There are no array literals. Build one by splitting a string, and do arithmetic with filters:

ValuesSample store data
4 sizes, last is XL

divided_by with two whole numbers drops the remainder; divide by 100.0 to keep it.

Coming from Shopify

ShopifyIn Joomni
Section files and {% schema %}The same. A section is one template with a schema at the top; pasted Shopify setting types are mapped automatically.
{% render %} snippetsSupported, from the theme’s own snippets. {% include %} is not.
{% style %}, {% stylesheet %}, {% javascript %}Supported, rendered inline where you wrote them.
section.blocks and block.shopify_attributesSupported. block.joomni_attributes is the same string.
request, routes, templateSupported, with Joomni’s URLs.
Forms ({% form %})Not available. Use data-joomni-action="lead-submit" on a normal <form>.
cart in page sectionsOnly in the cart drawer overlay. Use the cart widgets elsewhere.
Metafieldsproduct.custom_fields and product.metadata.

Still stuck? Our team reads every message.

Need help?