where

v8.1.0

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".

Input

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 %}

Output

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.

Input

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 %}

Output

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.

Input

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

Output

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 }
]

Input

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

Output

- 2
- 3

Jekyll style

v10.21.0

For Liquid users migrating from Jekyll, there’s a jekyllWhere option to mimic the behavior of Jekyll’s where filter. This option is set to false by default. When enabled, if property is an array, the target value is matched using Array.includes instead of ==, which is particularly useful for filtering tags. Additionally, a target value of undefined is treated normally, entries matched are exactly those which are themselves undefined.

This option affects other array selection filters as well, such as reject and find.

const pages = [
    { tags: ["cat", "food"], title: 'Cat Food' },
    { tags: ["dog", "food"], title: 'Dog Food' },
]

Input

{% assign selected = pages | where: 'tags', "cat" %}
{% for item in selected -%}
- {{ item.title }}
{% endfor %}

Output

Cat Food