Array filters

`first`

Returns the first item of an array.

{{ "Ground control to Major Tom." | split: " " | first }}

Ground

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.first }}

zebra

You can use first with dot notation when you need to use the filter inside a tag:

{% if my_array.first == "zebra" %}
  Here comes a zebra!
{% endif %}

`last`

Returns the last item of an array.

{{ "Ground control to Major Tom." | split: " " | last }}

Tom.

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.last }}

tiger

You can use last with dot notation when you need to use the filter inside a tag:

{% if my_array.last == "tiger" %}
  There goes a tiger!
{% endif %}

`join`

Combines the items in an array into a single string using the argument as a separator.

{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{{ beatles | join: " and " }}

John and Paul and George and Ringo

`reverse`

Reverses the order of the items in an array. reverse cannot reverse a string.

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}

{{ my_array | reverse | join: ", " }}

plums, peaches, oranges, apples

Although reverse cannot be used directly on a string, you can split a string into an array, reverse the array, and rejoin it by chaining together filters:

{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

.moT rojaM ot lortnoc dnuorG

`size`

Returns the number of characters in a string or the number of items in an array.

{{ "Ground control to Major Tom." | size }}

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}

{{ my_array.size }}

You can use size with dot notation when you need to use the filter inside a tag:

{% if site.pages.size > 10 %}
  This is a big website!
{% endif %}

`sort`

Sorts items in an array in case-sensitive order.

{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}

{{ my_array | sort | join: ", " }}

Sally Snake, giraffe, octopus, zebra

An optional argument specifies which property of the array’s items to use for sorting.

{% assign products_by_price = collection.products | sort: "price" %}
{% for product in products_by_price %}
  <h4>{{ product.title }}</h4>
{% endfor %}

`sort_natural`

Sorts items in an array in case-insensitive order.

{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}

{{ my_array | sort_natural | join: ", " }}

giraffe, octopus, Sally Snake, zebra

An optional argument specifies which property of the array’s items to use for sorting.

{% assign products_by_company = collection.products | sort_natural: "company" %}
{% for product in products_by_company %}
  <h4>{{ product.title }}</h4>
{% endfor %}

`map`

Creates an array of values by extracting the values of a named property from another object. In this example, assume the object site.pages contains all the metadata for a website. Using assign with the map filter creates a variable that contains only the values of the category properties of everything in the site.pages object.

{% assign all_categories = site.pages | map: "category" %}

{% for item in all_categories %}
- {{ item }}
{% endfor %}

- business
- celebrities
- lifestyle
- sports
- technology

`concat`

Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays.

{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}

{% assign everything = fruits | concat: vegetables %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- apples
- oranges
- peaches
- carrots
- turnips
- potatoes

You can string together concat filters to join more than two arrays:

{% assign furniture = "chairs, tables, shelves" | split: ", " %}

{% assign everything = fruits | concat: vegetables | concat: furniture %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
- chairs
- tables
- shelves

`uniq`

Removes any duplicate elements in an array.

{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %}
{{ my_array | uniq | join: ", " }}

ants, bugs, bees

`where`

Creates an array including only the objects with a given property value, or any truthy value by default. In this example, assume you have a list of products and you want to show your kitchen products separately. Using where, you can create an array containing only the products that have a "type" of "kitchen".

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.title }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Spatula
- Garlic press

Say instead you have a list of products and you only want to show those that are available to buy. You can where with a property name but no target value to include all products with a truthy "available" value. As a special case, the same will happen if the target value is given but evaluates to undefined.

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign available_products = products | where: "available" %}

Available products:
{% for product in available_products %}
- {{ product.title }}
{% endfor %}

All products:
- Coffee mug
- Limited edition sneakers
- Boring sneakers

Available products:
- Coffee mug
- Boring sneakers

The where filter can also be used to find a single object in an array when combined with the first filter. For example, say you want to show off the shirt in your new fall collection.

{% assign new_shirt = products | where: "type", "shirt" | first %}
Featured product: {{ new_shirt.title }}

Featured product: Hawaiian print sweater vest

Additionally, property can be any valid Liquid variable expression as used in output syntax, except that the scope of this expression is within each item. For the following products array:

const products = [
    { meta: { details: { class: 'A' } }, order: 1 },
    { meta: { details: { class: 'B' } }, order: 2 },
    { meta: { details: { class: 'B' } }, order: 3 }
]

{% assign selected = products | where: 'meta.details["class"]', "B" %}
{% for item in selected -%}
- {{ item.order }}
{% endfor %}

- 2
- 3

`slice`

Returns a substring of 1 character beginning at the index specified by the first argument. An optional second argument specifies the length of the substring to be returned. String indices are numbered starting from 0.

{{ "Liquid" | slice: 0 }}

{{ "Liquid" | slice: 2 }}

{{ "Liquid" | slice: 2, 5 }}

quid

If the first argument is a negative number, the indices are counted from the end of the string:

{{ "Liquid" | slice: -3, 2 }}

ui

`where_exp`

Select all the objects in an array where the expression is true. In this example, assume you have a list of products and you want to show your kitchen products separately. Using where_exp, you can create an array containing only the products that have a "type" of "kitchen".

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign kitchen_products = products | where_exp: "item", "item.type == 'kitchen'" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.title }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Spatula
- Garlic press

`find`

Return the first object in an array for which the queried attribute has the given value or return nil if no item in the array satisfies the given criteria. For the following members array:

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | find: "graduation_year", 2014 | json }}

{"graduation_year":2014,"name":"John"}

`find_exp`

Return the first object in an array for which the given expression evaluates to true or return nil if no item in the array satisfies the evaluated expression.

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | find_exp: "item", "item.graduation_year == 2014" | json }}

{"graduation_year":2014,"name":"John"}

`find_index`

Return the 0-based index of the first object in an array for which the queried attribute has the given value or return nil if no item in the array satisfies the given criteria. For the following members array:

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | find_index: "graduation_year", 2014 | json }}

`find_index_exp`

Return the 0-based index of the first object in an array for which the given expression evaluates to true or return nil if no item in the array satisfies the evaluated expression.

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | find_index_exp: "item", "item.graduation_year == 2014" | json }}

`group_by`

Group an array’s items by a given property. For members array:

const members = [
  { graduation_year: 2003, name: 'Jay' },
  { graduation_year: 2003, name: 'John' },
  { graduation_year: 2004, name: 'Jack' }
]

{{ members | group_by: "graduation_year" | json: 2 }}

[
  {
    "name": 2003,
    "items": [
      {
        "graduation_year": 2003,
        "name": "Jay"
      },
      {
        "graduation_year": 2003,
        "name": "John"
      }
    ]
  },
  {
    "name": 2004,
    "items": [
      {
        "graduation_year": 2004,
        "name": "Jack"
      }
    ]
  }
]

`group_by_exp`

Group an array’s items using a Liquid expression. For members array below:

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2009, name: 'Jack' }
]

{{ members | group_by_exp: "item", "item.graduation_year | truncate: 3, ''" | json: 2 }}

[
  {
    "name": "201",
    "items": [
      {
        "graduation_year": 2013,
        "name": "Jay"
      },
      {
        "graduation_year": 2014,
        "name": "John"
      }
    ]
  },
  {
    "name": "200",
    "items": [
      {
        "graduation_year": 2009,
        "name": "Jack"
      }
    ]
  }
]

`has`

Return true if the array includes an item for which the queried attribute has the given value or return false if no item in the array satisfies the given criteria. For the following members array:

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | has: "graduation_year", 2014 | json }}

true

`has_exp`

Return true if an item exists in an array for which the given expression evaluates to true or return false if no item in the array satisfies the evaluated expression.

const members = [
  { graduation_year: 2013, name: 'Jay' },
  { graduation_year: 2014, name: 'John' },
  { graduation_year: 2014, name: 'Jack' }
]

{{ members | has_exp: "item", "item.graduation_year == 2014" | json }}

true

`compact`

Removes any nil values from an array. For this example, assume site.pages is an array of content pages for a website, and some of these pages have an attribute called category that specifies their content category. If we map those categories to an array, some of the array items might be nil if any pages do not have a category attribute.

{% assign site_categories = site.pages | map: "category" %}

{% for category in site_categories %}
- {{ category }}
{% endfor %}

- business
- celebrities
-
- lifestyle
- sports
-
- technology

By using compact when we create our site_categories array, we can remove all the nil values in the array.

{% assign site_categories = site.pages | map: "category" | compact %}

{% for category in site_categories %}
- {{ category }}
{% endfor %}

- business
- celebrities
- lifestyle
- sports
- technology

`push`

Push an element into array. It’s NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.

{% assign fruits = "apples, oranges" | split: ", " %}

{% assign everything = fruits | push: "peaches" %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- apples
- oranges
- peaches

`pop`

Pop an element from the array. It’s NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.

{% assign fruits = "apples, oranges, peaches" | split: ", " %}

{% assign everything = fruits | pop %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- apples
- oranges

`shift`

Shift an element from the array. It’s NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.

{% assign fruits = "apples, oranges, peaches" | split: ", " %}

{% assign everything = fruits | shift %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- oranges
- peaches

`unshift`

Unshift an element to the front of the array. It’s NON-DESTRUCTIVE, i.e. it does not mutate the array, but rather make a copy and mutate that.

{% assign fruits = "oranges, peaches" | split: ", " %}

{% assign everything = fruits | unshift: "apples" %}

{% for item in everything %}
- {{ item }}
{% endfor %}

- apples
- oranges
- peaches

`reject`

Creates an array excluding the objects with a given property value, or excluding truthy values by default when a property is not given. In this example, assume you have a list of products and you want to filter out kitchen products. Using reject, you can create an array excluding only the products that have a "type" of "kitchen".

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign non_kitchen_products = products | reject: "type", "kitchen" %}

Kitchen products:
{% for product in non_kitchen_products %}
- {{ product.title }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Vacuum
- Television

Say instead you have a list of products and you want to exclude taxable products. You can reject with a property name but no target value to reject all products with a truthy "taxable" value.

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign not_taxed_products = products | reject: "taxable" %}

Available products:
{% for product in not_taxed_products %}
- {{ product.title }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Available products:
- Spatula
- Television

Additionally, property can be any valid Liquid variable expression as used in output syntax, except that the scope of this expression is within each item. For the following products array:

const products = [
    { meta: { details: { class: 'A' } }, order: 1 },
    { meta: { details: { class: 'B' } }, order: 2 },
    { meta: { details: { class: 'B' } }, order: 3 }
]

{% assign selected = products | reject: 'meta.details["class"]', "B" %}
{% for item in selected -%}
- {{ item.order }}
{% endfor %}

- 1

`reject_exp`

Select all the objects in an array where the expression is false. In this example, assume you have a list of products and you want to hide your kitchen products. Using reject_exp, you can create an array that omits only the products that have a "type" of "kitchen".

All products:
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign non_kitchen_products = products | reject_exp: "item", "item.type == 'kitchen'" %}

Kitchen products:
{% for product in non_kitchen_products %}
- {{ product.title }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Vacuum
- Television

Introduction

Key Concepts

References

`first`

`last`

`join`

`reverse`

`size`

`sort`

`sort_natural`

`map`

`concat`

`uniq`

`where`

`slice`

`where_exp`

`find`

`find_exp`

`find_index`

`find_index_exp`

`group_by`

`group_by_exp`

`has`

`has_exp`

`compact`

`push`

`pop`

`shift`

`unshift`

`reject`

`reject_exp`

​first

​last

​join

​reverse

​size

​sort

​sort_natural

​map

​concat

​uniq

​where

​slice

​where_exp

​find

​find_exp

​find_index

​find_index_exp

​group_by

​group_by_exp

​has

​has_exp

​compact

​push

​pop

​shift

​unshift

​reject

​reject_exp

`first`

`last`

`join`

`reverse`

`size`

`sort`

`sort_natural`

`map`

`concat`

`uniq`

`where`

`slice`

`where_exp`

`find`

`find_exp`

`find_index`

`find_index_exp`

`group_by`

`group_by_exp`

`has`

`has_exp`

`compact`

`push`

`pop`

`shift`

`unshift`

`reject`

`reject_exp`