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.
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.
| Operator | Meaning |
|---|---|
| == · != | Equal, not equal |
| > · < · >= · <= | Greater, less |
| and · or | Both, either. Evaluated right to left, and there are no parentheses: nest ifs instead. |
| contains | A string contains a substring, or an array contains a string: product.tags contains "sale" |
| blank · empty | product.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:
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.
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 · index0 | Position from 1 / from 0 |
| rindex · rindex0 | Position from the end |
| first · last | true on the first / last pass |
| length | How many passes in total |
| parentloop | The 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.
Build keys before you use them in 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:
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:
4 sizes, last is XL
divided_by with two whole numbers drops the remainder; divide by 100.0 to keep it.
Coming from Shopify
| Shopify | In 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 %} snippets | Supported, from the theme’s own snippets. {% include %} is not. |
| {% style %}, {% stylesheet %}, {% javascript %} | Supported, rendered inline where you wrote them. |
| section.blocks and block.shopify_attributes | Supported. block.joomni_attributes is the same string. |
| request, routes, template | Supported, with Joomni’s URLs. |
| Forms ({% form %}) | Not available. Use data-joomni-action="lead-submit" on a normal <form>. |
| cart in page sections | Only in the cart drawer overlay. Use the cart widgets elsewhere. |
| Metafields | product.custom_fields and product.metadata. |
Related guides