Skip to main content

Complex Values

We’ve talked a lot about keys that point to a single value, like this:

Hi {{ name }}!
Hi Lee!

But you can also have more complex values—which allow you to do a lot of cool things with tags. The complex values are objects and arrays


An object is a value that’s made up of key/value pairs. Remember that big box labeled dessert we discussed in the Liquid Fundamentals lesson on keys—the one with many other boxes of delicious treats inside? The value of that dessert key is all the other keys and their values inside the box.    

The customer key we discussed in the first lesson of this module is also an example of a key that points to an object. Here it is again: 


As you can see, inside those single curly brackets is a collection of keys with their associated values—the whole shebang is the object

This is where that dot notation we covered in Liquid Fundamentals comes in—a key to reference the object, then another key to reference the specific value inside that big collection of key/value pairs, like this:

Hi {{ customer.first_name }}!
Hi Lee!

When you’re dealing with an object, the order of the key/value pairs inside doesn’t matter—your dot notation tells Liquid the exact value to output. 


An array also contains multiple bits of information, but instead of key/value pairs, an array contains either a list of values, which can be strings, numbers, or even objects. 

You can tell you’re looking at an array because, in JSON, it’s enclosed in square brackets instead of curly brackets. 

Let’s say we have a key called pet_names, and the value the key points to is an array.  In this example, the array is a list of strings.   

["spot", "milo", "otis"]

One of the most useful things about arrays is that they allow you to nest data. As we said, an array can also be a list of objects. That’s going to look more complicated at first. Here’s an example, in JSON, of a key called pets whose value type is an array:

[ { "name": "spot", "age": 12, "breed": "dachshund" }, { "name": "milo", "age": 7, "breed": "corgi" }, { "name": "otis", "age": 3, "breed": "whippet" } ]

Yep, looks complicated! But the principle is no different than if the array is a list of strings. Let’s break it down:

  • We see the square brackets enclose the whole thing: we know it’s an array
  • Inside the square brackets, we see sets of curly brackets: we know each set of items in curly brackets is an object
  • We know that an object contains collection of key/value pairs, and that’s exactly what we see inside each set of curly brackets!

It’s like a set of Matryoshka dolls—each element nested inside another. 

An important aspect of arrays is that the values (whether those values are strings, numbers, or objects) are organized in a specific sequence. Why does the order matter? Well as you know, the magic of Liquid comes from how keys, filters, and tags all work together. When you have a key whose value is an array, you can have filters and tags refer to the various values within it based on their specific order.

Sounds like a perfect segue into our next lesson! 

Up Next: Intermediate filters