Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 61 ยท Liquid Basics

Conditions: if, unless, case

Learn Shopify Liquid conditions: if, elsif, else, unless and case/when, comparison operators, contains, and/or, empty vs blank and nil handling, with live examples.

Almost every theme template makes decisions. Show a "Sold out" badge only when a product is unavailable. Print the sale price only when there is a compare-at price. Pick a different icon for each payment type. In Liquid these decisions are written with conditional tags: if, unless and case.

This lesson covers all three, the comparison operators you can use inside them, and the part that trips up most newcomers: what Liquid treats as "true". The examples target Liquid as it works in current Online Store 2.0 themes; Liquid is not tied to an Admin API version, so nothing here changes with API releases. If you have not met {{ }} and {% %} yet, read Liquid Basics: Output, Objects and Whitespace first.

Shopify's Liquid engine runs on Shopify's servers, so you cannot run real theme code on this site. The theme snippets below are read-only. The runnable examples use a small Liquid-style engine written in JavaScript. It follows the same rules for the features shown here, but it is a teaching stand-in, not Shopify's code.

if, elsif and else

An if block renders its content only when the condition is true. You can add any number of elsif branches and one final else. The block must be closed with endif.

LIQUID
{% if product.available == false %}
  Sold out
{% elsif product.compare_at_price > product.price %}
  On sale
{% else %}
  {{ product.price | money }}
{% endif %}

Branches are checked from top to bottom and only the first match is rendered. Note the spelling: elsif, not elseif or else if. A misspelled tag is a Liquid error, and Shopify prints the error text into the page instead of your content.

Conditions can be a single value (is it truthy?) or a comparison of two values.

Operator Meaning
== equal
!= or <> not equal
>, <, >=, <= greater or less than
contains a string contains a substring, or an array of strings contains a string

contains is case sensitive, and on an array it checks for a whole element: product.tags contains 'sale' is true for the tag sale, but product.tags contains 'sal' is false. It cannot search an array of objects, such as cart.items.

flowchart TD
    A["Start of if block"] --> B{"First condition true?"}
    B -- yes --> R1["Render first branch"]
    B -- no --> C{"elsif condition true?"}
    C -- yes --> R2["Render elsif branch"]
    C -- no --> D{"else branch present?"}
    D -- yes --> R3["Render else branch"]
    D -- no --> E["Render nothing"]
    R1 --> F["endif"]
    R2 --> F
    R3 --> F
    E --> F

Liquid checks branches in order and stops at the first one that matches.

Truthy and falsy: not what JavaScript does

This is the rule to memorize: in Liquid only false and nil are falsy. Everything else is truthy, including 0, an empty string "", an empty array and the string "false".

nil is what Liquid gives you for something that does not exist: a misspelled property, a metafield that was never filled in, product.vendor on an object that has no such key. That is why this common pattern works:

LIQUID
{% if section.settings.heading %}
  <h2>{{ section.settings.heading }}</h2>
{% endif %}

Be careful, though: a text setting that a merchant has cleared can be an empty string, and an empty string is truthy, so the <h2> could be printed with nothing inside. When you want "has real content", use != blank instead:

LIQUID
{% if section.settings.heading != blank %}
  <h2>{{ section.settings.heading }}</h2>
{% endif %}

empty and blank

Two special words help here, and you write them without quotes:

  • empty is true for a string, array or hash with zero length.
  • blank is broader: it is also true for nil, false and strings that contain only whitespace.

For checking whether a text value has content, blank is almost always the right choice. The second example further down prints a table so you can compare JavaScript truthiness, Liquid truthiness, blank and empty side by side.

Also remember that nil == false is false: they are different values. If a setting could be missing, test for it with blank or plain truthiness rather than comparing to false. And comparisons across types do not coerce: the number 1 is not equal to the string "1". Values from the settings object keep their schema type, but anything you build yourself from text (for example with split) is a string.

unless

unless is if with the condition inverted. The content renders when the condition is false.

LIQUID
{% unless product.tags contains 'hidden' %}
  {% render 'product-card', product: product %}
{% endunless %}

It reads well for a single, simple negative. Avoid unless with and/or or with else; people misread the double negatives. Rewrite those as if.

case and when

When one value is compared against several possibilities, case is cleaner than a ladder of elsif:

LIQUID
{% case product.type %}
  {% when 'Shoes' %}
    Show the shoe size guide
  {% when 'Jackets', 'Coats' %}
    Show outerwear care tips
  {% else %}
    Show general info
{% endcase %}

A when can list several values separated by commas (or the word or). The else branch is optional and runs only if no when matched. Match values with case are compared with ==, so they are also case sensitive and type sensitive. Do not write two when lines that can match the same value: Liquid renders every matching when block, which is rarely what you want.

and, or and the "right to left" rule

You can combine tests with and and or:

LIQUID
{% if product.available and product.tags contains 'new' %}
  <span class="badge">New</span>
{% endif %}

Unlike most languages, Liquid has no operator precedence and no parentheses. A condition with several and/or operators is evaluated from right to left. So A and B or C means A and (B or C), while many other languages read it as (A and B) or C. When your logic needs a specific grouping, do not fight the language: split the test into steps with assign (next-but-one lesson), or nest if blocks.

LIQUID
{% assign is_discounted = false %}
{% if product.compare_at_price > product.price %}
  {% assign is_discounted = true %}
{% endif %}
{% if is_discounted and product.available %}
  Discounted and in stock
{% endif %}

Try it: a stand-in engine

The editor below contains the small engine (a couple of hundred lines, mostly plumbing) and runs several templates against a product object. Change the data or the templates and run again. Notice which branch wins, how unless and case behave, how blank and empty differ, and how the and/or rule changes a result.

JS Conditions in a mini Liquid engine

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

No output.

What is real here, and what is not? The tags, operators, truthiness rules and the right-to-left evaluation match how Liquid behaves. The parser, the error handling and the output formatting are simplified stand-ins, and only a handful of filters exist. On a real store, a failed condition would print a Liquid error message into the page, not throw an exception.

Truthiness lab

The second example is plain JavaScript. It prints a table of values and what each rule says about them. Compare the JS if and Liquid if columns: 0, "" and []/{} are the interesting ones.

JS JavaScript truthiness vs Liquid truthiness

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

No output.

Conditions you will use in real themes

A few patterns you will see again and again in theme code:

LIQUID
{% if cart.item_count > 0 %}โ€ฆ{% endif %}
{% if collection.products_count == 0 %}No products found{% endif %}
{% if customer %}Hello, {{ customer.first_name }}{% endif %}
{% if template.name == 'product' %}โ€ฆ{% endif %}
{% if product.metafields.custom.care_guide != blank %}โ€ฆ{% endif %}
  • customer is nil for a visitor who is not logged in, so a plain {% if customer %} is a login check.
  • template.name tells a shared snippet which page it is on. More about the global objects comes in The Global Objects You Use Most.
  • Metafields that were never set are nil; != blank also protects you from an empty string.

Keep conditions out of loops when you can compute the answer once before the loop. Every check inside a loop of 50 products runs 50 times; see Liquid Performance later in the course.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these values is falsy in Liquid?

    Only false and nil are falsy in Liquid. Zero, empty strings and empty arrays are all truthy, which differs from JavaScript for 0 and the empty string.
  2. 2. A text setting was saved empty. Which test correctly says it has no content?

    blank is true for nil, false, empty strings and whitespace-only strings. Comparing to false fails for an empty string, because an empty string is not equal to false.
  3. 3. How does Liquid read the condition A and B or C?

    Liquid has no operator precedence and no parentheses. Operators are evaluated right to left, so A and B or C groups as A and (B or C).
  4. 4. product.tags contains 'sal' when the product has the tag sale. What is the result?

    On an array of strings, contains checks whether an element equals the given string. A partial string only matches when you use contains on a single string value.

Summary

  • if, elsif (not elseif) and else pick the first matching branch; unless runs when the test is false; case/when compares one value against several.
  • Comparison operators: ==, !=, <>, >, <, >=, <= and contains (case sensitive; on arrays it needs a whole element).
  • Only false and nil are falsy. 0, "" and [] are truthy.
  • Use blank to test for "no real content" and empty for zero length; remember nil == false is false and 1 == "1" is false.
  • and/or run right to left with no parentheses: split complex logic into steps.

Next: Loops: for, break, limit, offset, forloop