Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 61 ยท Liquid Basics

Liquid Basics: Output, Objects and Whitespace

Learn the core of Liquid: output with double braces, tags, objects, dot and bracket access, comments, whitespace control and truthy and falsy values.

Liquid is the template language of Shopify themes. It was created by Shopify and is now open source. A Liquid file looks like HTML with a few extra pieces: double curly braces that print a value, and curly-brace-percent tags that make decisions or repeat things. Shopify runs Liquid on its servers, fills in data from the store, and sends the finished HTML to the shopper.

Every other part of theme development depends on it. Sections, snippets, templates and the layout are all Liquid files. This lesson covers the building blocks: output, tags, objects, how to reach into them, comments, whitespace and truthiness. The following lessons add conditions, loops, variables and filters.

Shopify's real Liquid engine runs on Shopify's servers, so it cannot run here. The live editors in this lesson use a small Liquid-style engine written in JavaScript (about a hundred lines, visible in the code). It is a stand-in that follows the real rules for the features shown, but it does not cover everything the real engine does. Code blocks that are not editable are real Liquid you would put in a theme file.

Two kinds of markup

Liquid has three kinds of syntax, and you can tell them apart by the delimiters.

Syntax Name What it does
{{ ... }} Output Prints a value into the page
{% ... %} Tag Logic and control: conditions, loops, assignments, includes
| filter Filter Changes an output value, used inside {{ }}

Everything outside the delimiters is plain text and passes through unchanged. That is why a Liquid file can be a normal HTML page with a few dynamic spots.

LIQUID
<h1>{{ product.title }}</h1>
{% if product.available %}
  <p>In stock</p>
{% endif %}

The first line prints the product's title. The if tag decides whether the paragraph appears. Tags that open something (if, for) need a closing tag (endif, endfor).

Output: printing values

Anything inside {{ }} is evaluated and its value is written into the HTML. If the value does not exist, Liquid prints nothing and does not raise an error.

LIQUID
{{ shop.name }}
{{ "Hello" }}
{{ 42 }}
{{ product.title | upcase }}

You can print string literals (single or double quotes), numbers and objects' properties. Unlike a few other template systems, Liquid in Shopify does not escape output automatically. If a value might contain characters like < and & from user input, you add the escape filter yourself. This matters for safety; see Security in Themes.

Objects and how to reach into them

Shopify gives every template a set of objects: product, collection, shop, cart, customer, settings, and more (The Global Objects You Use Most lists them). An object has properties, and you read them with a dot:

LIQUID
{{ product.title }}
{{ product.vendor }}
{{ shop.name }}

Properties can be nested, so you chain dots: {{ product.featured_image.alt }}.

Bracket access

Square brackets do the same thing with a string or a variable, which is useful when the name is stored somewhere or contains characters a dot cannot handle:

LIQUID
{{ product["title"] }}
{% assign field = "vendor" %}
{{ product[field] }}
{{ settings["color-primary"] }}

The last line is important: a name with a hyphen needs brackets. Metafield and settings ids with unusual characters are the common case.

Arrays and size

Lists are arrays. You can pick an item by index, starting at 0, and ask for the length with size:

LIQUID
{{ product.tags[0] }}
{{ product.tags.size }}
{{ product.tags.first }}
{{ product.tags.last }}

first, last and size are special properties available on arrays (and size on strings). There is no length.

Try it: output, objects and filters

The editor below defines a small product and a template. Edit the template and run it again: change a property name, remove a closing quote, ask for something that does not exist, and see what happens. The engine supports output, a few filters (upcase, downcase, capitalize, append, prepend, join, first, size, default), assign, if, comment and raw.

JS A mini Liquid engine: output and objects

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

No output.

Two behaviors to notice. A missing property (product.subtitle) prints as empty text and does not stop the page. And default supplies a fallback only when the value is missing, false or empty. That forgiving behavior is useful, but it also hides typos: a misspelled property silently prints nothing. Theme Check and careful testing catch these (Liquid Pitfalls and Debugging).

Comments

To leave a note for other developers, or to disable code temporarily, use a comment block. Everything inside, including Liquid, is not run and is not sent to the browser:

LIQUID
{% comment %}
  TODO: show the vendor once the design is approved
  {{ product.vendor }}
{% endcomment %}

For one line there is an inline comment form, and inside a multi-line {% liquid %} tag you can use # too:

LIQUID
{% # This is an inline comment %}
{%- liquid
  # Everything in this tag is Liquid code, no delimiters needed
  assign title = product.title | upcase
  echo title
-%}

The liquid tag lets you write many tags without repeating delimiters, and echo is its way to print a value. Another special tag is raw, which prints its content exactly as written. It is the way to show {{ }} as text, for instance when a theme includes a JavaScript template literal:

LIQUID
{% raw %}{{ this is not Liquid }}{% endraw %}

HTML comments (<!-- ... -->) are different. They are just text to Liquid: Liquid still runs inside them, and the comment is delivered to the browser, so anyone can read it in the page source. Use Liquid comments for anything internal.

Whitespace control

Liquid tags leave their line breaks and spaces behind. Output of a loop can end up full of blank lines. Browsers usually collapse whitespace between HTML elements, so this rarely changes how a page looks, but it can matter inside <pre>, inline elements, attributes and generated JSON.

Add a hyphen to a delimiter to trim whitespace on that side:

  • {{- or {%- removes whitespace before the tag.
  • -}} or -%} removes whitespace after it.
LIQUID
<p>
  {%- if product.available -%}
    In stock
  {%- endif -%}
</p>

Without hyphens, that paragraph contains spaces and new lines around "In stock". With them, it prints <p>In stock</p>. Many themes put hyphens on most tags by habit, and that is good style. Do not rely on a hyphen to hide meaningful spaces between words, though: if you trim both sides of an inline value you may glue words together.

Try it: whitespace and truthiness

This second editor shows the effect of whitespace control, then runs the same if against different kinds of values. The output uses JSON.stringify for the spaces so you can see exactly what is printed.

JS Whitespace control and truthy values

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

No output.

Truthy and falsy

In a condition, Liquid treats only two values as false: nil (nothing, a missing value) and false. Everything else is true, including values that JavaScript treats as false:

  • the empty string "" is truthy;
  • the number 0 is truthy;
  • an empty array is truthy.

This surprises people who come from JavaScript or PHP. To test for "has content", compare to the special words empty or blank (covered in Conditions: if, unless, case), not just the variable by itself.

How Liquid differs from JavaScript

Idea JavaScript Liquid
False values false, 0, "", null, undefined, NaN Only false and nil
Combine conditions &&, ||, ! and, or (no not operator; use unless or !=)
Math a + b Filters: {{ a | plus: b }}
Missing property undefined, and null.x throws nil, which prints nothing, and chains do not throw
Output escaping Depends on the framework None by default; use escape
Where it runs Browser or Node, can react to clicks Shopify's server, once per request
Equality == converts types, === does not == does not convert: the string "5" is not equal to the number 5

Keep this table in mind; it explains most beginner bugs. Liquid is intentionally limited: it cannot define functions, make network requests or change the page after it loads. Use JavaScript for those jobs (JavaScript in Themes).

Putting it together in a theme

Here is a short, realistic snippet using everything from this lesson (real Liquid, read-only). It prints a vendor line only when there is a vendor, keeps its HTML tidy with hyphens and leaves a note for other developers:

LIQUID
{% comment %} Product byline shown under the title {% endcomment %}
<div class="byline">
  {%- if product.vendor != blank -%}
    <span>By {{ product.vendor | escape }}</span>
  {%- endif -%}
  <span>{{ product.tags.size }} tags</span>
</div>

You will see this style throughout Dawn (Exploring Dawn).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which delimiters print a value into the page?

    Double curly braces are output. Curly-brace-percent delimiters are tags for logic.
  2. 2. Which values does Liquid treat as false in a condition?

    Liquid is stricter than JavaScript. The empty string, 0 and empty arrays are all truthy.
  3. 3. How do you read a setting whose id contains a hyphen, such as color-primary?

    A dot cannot handle the hyphen, so use bracket access with a quoted string.
  4. 4. What does {%- if x -%} do differently from {% if x %}?

    A hyphen inside the delimiter removes whitespace on that side of the tag, which keeps generated HTML tidy.
  5. 5. Why use {% comment %} instead of an HTML comment for internal notes?

    Liquid comments are removed on the server. HTML comments are delivered to every visitor, and Liquid still runs inside them.

Summary

  • {{ }} prints values, {% %} runs tags, and | applies filters inside output.
  • Read object properties with dots or brackets; arrays have first, last and size.
  • A missing value is nil: it prints nothing and does not stop the page.
  • Only nil and false are falsy. Empty strings, 0 and empty arrays are truthy.
  • Liquid comments stay on the server; hyphens in delimiters trim whitespace.
  • Liquid runs once on the server and has no functions or operators like JavaScript.

Next, make pages react to data with Conditions: if, unless, case.