Array filters

Filters for ordering, transforming, and querying lists — including the microdata items a resource binding yields. Standard Shopify Liquid unless marked extension.

Ordering and elements

first

The first element of an array (or first character of a string). nil if empty.

{{ items | first }}

last

The last element of an array (or last character of a string).

{{ items | last }}

reverse

Reverses the array.

{{ "a,b,c" | split: "," | reverse | join: "," }}   <!-- c,b,a -->

sort

Sorts the array. With a field name, sorts an array of objects by that field.

{{ "banana,apple,cherry" | split: "," | sort | join: ", " }}   <!-- apple, banana, cherry -->
{% assign newest = posts | sort: "date" %}

sort_natural

Case-insensitive lexical sort.

{{ "b,A,c" | split: "," | sort_natural | join: "" }}   <!-- Abc -->

uniq

Removes duplicate elements, preserving order.

{{ "a,b,a,c" | split: "," | uniq | join: "," }}   <!-- a,b,c -->

compact

Removes nil elements.

{{ list | compact | join: ", " }}

Transforming and joining

map

Extracts a field from every object in the array.

{{ people | map: "name" | join: ", " }}

join

Joins the elements into a string with a separator (default a space).

{{ tags | join: ", " }}

concat

Concatenates a second array onto the input.

{% assign all = drafts | concat: published %}

Querying an array of objects

These operate on an array of objects and let a template filter, find, and test them without a {% for %} loop.

Each takes a field name and an optional expected value: array | filter: "field", value matches items whose field equals value; with the value omitted, array | filter: "field" matches items whose field is truthy. Non-object elements never match. For a full expression rather than field equality, see the expression-variant filters.

where

The sub-array of matching items. (Standard Liquid.)

{{ people | where: "role", "admin" | map: "name" | join: ", " }}

reject

(extension) The sub-array of non-matching items — the inverse of where.

{% assign active = users | reject: "suspended", true %}

find

(extension) The first matching element (or nil).

{{ products | find: "sku", "A-1" | map: "title" }}

find_index

(extension) The index of the first matching element (or nil).

{{ products | find_index: "sku", "A-1" }}   <!-- 0 -->

has

(extension) A boolean — whether any element matches.

{% if products | has: "onsale", true %}Sale on now!{% endif %}

group_by

(extension) Groups the array by a field, returning an array of { name, items } objects in first-seen key order.

{% assign by_year = posts | group_by: "year" %}
{% for group in by_year %}
  <h2>{{ group.name }}</h2>
  <ul>{% for post in group.items %}<li>{{ post.title }}</li>{% endfor %}</ul>
{% endfor %}

sum

(extension) Totals the array. With no argument it sums the array's numbers; with a field name it sums that property across an array of objects. Non-numeric values count as 0; the result is an integer when whole, otherwise a float.

{{ prices | sum }}                <!-- total of the numbers -->
{{ line_items | sum: "price" }}   <!-- total of each item's price -->

Mutation

Each returns a new array — the input is never mutated — so they compose in a pipeline or an {% assign %}. All are extensions.

push

(extension) Appends a value, returning a new array. Standard Liquid has no array-append filter — concat only joins two arrays — so push fills the gap. The input is coerced to an array first: an array is appended to; nothing (an unassigned variable) becomes a one-element array; any other single value is promoted to a one-element array first.

Pushing onto an unassigned variable is the idiomatic way to build a list in a loop:

{% for term in terms %}
  {% assign wanted = wanted | push: term %}
{% endfor %}
{{ wanted | join: ", " }}

wanted is never assigned before the loop, so on the first iteration it is nil and push returns a one-element array; each later iteration appends. This avoids a common footgun: {% assign a = "" | split: "," %} does not produce an empty array — it produces [""].

unshift

(extension) Prepends a value, returning a new array. LiquidJS-compatible.

{% assign crumbs = crumbs | unshift: "Home" %}

pop

(extension) Returns a new array without the last element. LiquidJS-compatible.

{% assign rest = items | pop %}

shift

(extension) Returns a new array without the first element. LiquidJS-compatible.

{% assign tail = items | shift %}