Liquid Types

• String
• Boolean
• Number
• Nil
• Hash (Object)
• Array
• Empty
• Truthy and Falsy values

String

Declare a string by wrapping a variable's value in single or double quotes:

{% assign my_string = 'Hello World!' %}

A backslash escapes the next character in a string. Put a backslash before a quote to use a quote of the same kind inside a string, for example . Write two backslashes for one backslash. Any other backslash, such as d in a pattern, stays as written.

Boolean

Booleans are either or . No quotations are necessary when declaring a boolean:

{% assign foo = true %}
{% assign bar = false %}

Number

Numbers include floats and integers:

{% assign my_int = 25 %}
{% assign my_float = 39.756 %}

Nil

Nil is a special empty value that is returned when the Liquid code has no results. It is not a string with the characters 'nil'.

Nil is treated as in the conditions of if blocks and other Liquid tags that check the truthfulness of a statement.

In the following example, if the user does not exist (that is, the user returns nil), Liquid will not print the greeting:

{% if user %}
  Hello {{ user.name }}!
{% endif %}

Tags or outputs that return nil will not print anything to the page.

Input

The current user is {{ user.name }}

Output

The current user is

Hash (Object)

Hash represents an object as a key value dictionary, allowing a value to be another Hash. The most used hash is context, a built-in global object.

Initializing a new object

To create a hash, assign a hash literal. As in JSON, keys are written in double quotes, a key can also be a variable, and literals can be nested. You can also start from an empty hash and set keys with dot or bracket notation:

{% assign my_object = {} %}
{% assign my_object.hello = 'world' %}

The parse_json tag and filter are deprecated for JSON you write in the template. Use parse_json only to turn a JSON string that arrives at runtime, such as an API response, into a hash: .

Accessing object attributes

To access a value of an object, you can use dot notation or bracket [] notation if you would like to use variables instead of a hardcoded key.

Input

{{ my_object.hello }}
{%- assign var = 'hello' -%}
{{ my_object[var] }}

Output

world
world

Array

Arrays hold lists of variables of any type.

Accessing Items in Arrays

You can loop through each item using an iteration tag to access all the items in an array.

Input

{% comment %} if site.users = 'Tobi', 'Laura', 'Tetsuro', 'Adam' {% endcomment %}
{% for user in site.users %}
  {{ user }}
{% endfor %}

Output

Tobi Laura Tetsuro Adam

Accessing Specific Items in an Array

You can use square bracket [ ] notation to access a specific item in an array. Array indexing starts at zero.

Input

{% comment %} if site.users = 'Tobi', 'Laura', 'Tetsuro', 'Adam' {% endcomment %}
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}

Output

Tobi
Laura
Adam

Initializing Arrays

Create an array with an array literal. Items can be numbers, strings or variables, and [] is an empty array. Append to an existing array with <<, for example .

The split filter turns a string into an array of strings.

{% assign arr = [1, 2, 3, 4, 5] %}
{{ arr | join: ', ' }} => 1, 2, 3, 4, 5

{% assign words = 'one,two,three' | split: ',' %}
{{ words.size }} => 3

Searching in Arrays

These are the two methods you can use to search arrays

contains

You can check for the presence of a substring in a string, but can also check for the presence of a string in an array of strings. You can use it only for searching strings. You cannot use it to check for an object in an array of objects.

{% comment %} site.users = ['Tobi', 'Laura', 'Tetsuro', 'Adam'] {% endcomment %}
{% if site.users contains 'Tobi' %}
  Tobi is in users.
{% endif %}

array_any

Parameters:

• array (Array) - array to search in - default: []
• query (StringNumber) - String/Number compared to each item in the given array - default: 'true'

{% comment %} site.users = ['Tobi', 'Laura', 'Tetsuro', 'Adam'] {% endcomment %}
{% if site.users | array_any: 'Tobi' %}
  Tobi is in users.
{% endif %}

Empty

An object is returned if you try to access an object that is defined but has no value. For example, a page or product deleted or a setting with no value.

You can compare an object with to check whether an object exists before you access any of its attributes.

Truthy and Falsy Values

In programming, anything that returns true in a conditional (return true by default) is called truthy. Anything that returns false in a conditional (return false by default) is called falsy. All object types can be described as either truthy or falsy.

Truthy

All values in Liquid are truthy except nil and false.

In the example below, the string 'Tobi' is not a boolean, but it is truthy in a conditional:

{% assign tobi = 'Tobi' %}

{% if tobi %}
  This condition will always be true.
{% endif %}

Strings, even when empty, are truthy. The example below will result in empty HTML tags if is empty.

Input

{% if settings.fp_heading %}
  <h2>{{ settings.fp_heading }}</h2>
{% endif %}

Output

<h2></h2>

Falsy

The falsy values in Liquid are nil and false.

Truthy and Falsy Summary Table