Liquid basics

The basic concepts that you need to effectively interact with Liquid tags, filters, and objects.

# Basics

The following are basic concepts that you need to effectively interact with Liquid tags, filters, and objects.

## Object handles

Objects that represent store resources, such as products, collections, articles, and blogs, have handles for identifying an individual resource. The handle is used to build the URL for the resource, or to return properties for the resource.

Other objects like `linklists`, `links`, and `settings` also have handles.

## Creating and modifying handles

Handles are automatically generated based on the resource title. They follow a set of rules:

* Handles are always lowercase
* whitespace and special characters are replaced with a hyphen `-`
* If there are multiple consecutive whitespace or special characters, then they're replaced with a single hyphen
* Whitespace or special characters at the beginning are removed

Handles need to be unique, so if a duplicate title is used, then the handle is auto-incremented by one. For example, if you had two products called `Potion`, then their handles would be `potion` and `potion-1`.

After a resource has been created, changing the resource title doesn't update the handle.

You can modify a resource's handle within the Shopify admin. This can be done either in the Handle or the Edit website SEO sections, depending on the resource. If you reference resources by their handle, then be sure to update those references when modifying handles.

> **Note:**
> Individual links from `linklists` have handles based on their titles. These handles can't be modified directly. Individual settings, from `settings_schema.json`, sections, or blocks, get their handle from their `id` property.

## Referencing handles

All objects that have a handle have a `handle` property. For example, you can output a product's handle with `product.handle`. You can reference an object, from within its parent object, by its handle in two ways:

---

* Square bracket notation `[ ]`: Accepts a handle wrapped in quotes `'`, a Liquid variable, or an object reference
* Dot notation `.`: Accepts a handle without quotes

> **Note:**
> Referencing an object by its handle is similar to [referencing array elements by their index](#array).

## Logical and comparison operators

Liquid supports basic logical and comparison operators for use with [conditional tags](/docs/api/liquid/tags/conditional-tags).

| Operator | Function |
|----------|----------|
| == | equals |
| != | does not equal |
| > | greater than |
| < | less than |
| <= | less than or equal to |
| or | Condition A or Condition B |
| and | Condition A and Condition B |
| contains | Checks for strings in strings or arrays |

## contains

You can use `contains` to check for the presence of a string within an array, or another string. You can't use `contains` to check for an object in an array of objects.

## Order of operations

When using more than one operator in a tag, the operators are evaluated from right to left, and you can't change this order.

> **Caution:**
> Parentheses `()` aren't valid characters within Liquid tags. If you try to include them to group operators, then your tag won't be rendered.

## Types

Liquid output can be one of six data types.

### string

Any series of characters, wrapped in single or double quotes.

> **Tip:**
> You can check whether a string is empty with the `blank` object.

### number

Numeric values, including floats and integers.

### boolean

A binary value, either `true` or `false`.

### nil

An undefined value.

Tags or outputs that return `nil` don't print anything to the page. They are also treated as `false`.

> **Note:**
> A string with the characters "nil" is not treated the same as `nil`.

### array

A list of variables of any type.

To access all of the items in an array, you can loop through each item in the array using a `for` or `tablerow` tag.

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

You can't initialize arrays using only Liquid. You can, however, use the split filter to break a single string into an array of substrings.

### empty

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

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

## Truthy and falsy

All data types must return either `true` or `false`. Those which return `true` by default are called truthy. Those that return `false` by default are called falsy.

| Value | Truthy | Falsy |
|-------|---------|--------|
| true | true | false |
| false | false | true |
| nil | false | true |
| empty string | true | false |
| 0 | true | false |
| integer | true | false |
| float | true | false |
| array | true | false |
| empty array | true | false |
| page | true | false |
| empty object | true | false |

## Example

Because `nil` and `false` are the only falsy values, you need to be careful how you check values in Liquid. A value might not be in the format you expect, but still be truthy.

For example, empty strings are truthy, so you need to check whether they're empty with `blank`. `EmptyDrop` objects are also truthy, so you need to check whether the object you're referencing is `empty`.

## Whitespace control

Even if it doesn't output text, any line of Liquid outputs a line in your rendered content. By including hyphens in your Liquid tag, you can strip any whitespace that your Liquid generates when rendered.

If you want to remove whitespace on only one side of the Liquid tag, then you can include the hyphen on either the opening or closing tag.