Standard filters
================
.. note::
This page describes "standard" filters. Python Liquid also has some extra filters and
extended expression syntax that are disabled by default. See :doc:`extra_filters` and
:doc:`expressions` for documentation on non-standard features.
abs
---
.. code-block:: text
| abs
Return the absolute value of a number. Works on integers, floats and string
representations of integers or floats.
.. code-block:: liquid2
{{ -42 | abs }}
{{ 7.5 | abs }}
{{ '42.0' | abs }}
.. code-block:: text
:caption: output
42
7.5
42.0
Given a value that can't be cast to an integer or float, ``0`` will be returned.
.. code-block:: liquid2
{{ 'hello' | abs }}
{{ nosuchthing | abs }}
.. code-block:: text
:caption: output
0
0
append
------
.. code-block:: text
| append:
Return the input value concatenated with the argument value.
.. code-block:: liquid2
{{ 'Hello, ' | append: 'World!' }}
.. code-block:: text
:caption: output
Hello, World!
If either the input value or argument are not a string, they will be coerced to a string
before concatenation.
.. code-block:: liquid2
{% assign a_number = 7.5 -%}
{{ 42 | append: a_number }}
{{ nosuchthing | append: 'World!' }}
.. code-block:: text
:caption: output
427.5
World!
at_least
--------
.. code-block:: text
| at_least:
Return the maximum of the filter's input value and its argument. If either input value or
argument are string representations of an integer or float, they will be cast to an
integer or float prior to comparison.
.. code-block:: liquid2
{{ -5.1 | at_least: 8 }}
{{ 8 | at_least: '5' }}
.. code-block:: text
:caption: output
8
8
If either input value or argument can not be cast to an integer or float, ``0`` will be
used instead.
.. code-block:: liquid2
{{ "hello" | at_least: 2 }}
{{ "hello" | at_least: -2 }}
{{ -1 | at_least: "abc" }}
.. code-block:: text
:caption: output
2
0
0
at_most
-------
.. code-block:: text
| at_most:
Return the minimum of the filter's input value and its argument. If either input value or
argument are string representations of an integer or float, they will be cast to an
integer or float prior to comparison.
.. code-block:: liquid2
{{ 5 | at_most: 8 }}
{{ '8' | at_most: 5 }}
.. code-block:: text
:caption: output
5
5
If either input value or argument can not be cast to an integer or float, ``0`` will be
used instead.
.. code-block:: liquid2
{{ "hello" | at_most: 2 }}
{{ "hello" | at_most: -2 }}
{{ -1 | at_most: "abc" }}
.. code-block:: text
:caption: output
0
-2
-1
capitalize
----------
.. code-block:: text
| capitalize
Return the input string with the first character in upper case and the rest lowercase.
.. code-block:: liquid2
{{ 'heLLO, World!' | capitalize }}
.. code-block:: text
:caption: output
Hello, world!
If the input value is not a string, it will be converted to a string.
.. code-block:: liquid2
{{ 42 | capitalize }}
.. code-block:: text
:caption: output
42
ceil
----
.. code-block:: text
| ceil
Round the input value up to the nearest whole number. The input value will be converted to
a number if it is not an integer or float.
.. code-block:: liquid2
{{ 5.1 | ceil }}
{{ 5.0 | ceil }}
{{ 5 | ceil }}
{{ '5.4' | ceil }}
.. code-block:: text
:caption: output
6
5
5
5
If the input is undefined or can't be converted to a number, ``0`` is returned.
.. code-block:: liquid2
{{ 'hello' | ceil }}
{{ nosuchthing | ceil }}
.. code-block:: text
:caption: output
0
0
compact
-------
.. code-block:: text
| compact[: ]
Remove ``nil`` or ``null`` (or ``None`` in Python) values from an array-like object. If
given, the argument should be the name of a property that exists on each item (hash, dict
etc.) in the array-like sequence.
For example, if ``pages`` is an array of objects, some of which have a ``category``
property:
.. code-block:: json
:caption: data
{
"pages": [
{ "category": "business" },
{ "category": "celebrities" },
{},
{ "category": "lifestyle" },
{ "category": "sports" },
{},
{ "category": "technology" }
]
}
Without ``compact``, iterating those categories will include ``nil`` / ``null`` values.
.. code-block:: liquid2
{% assign categories = pages | map: "category" -%}
{% for category in categories -%}
- {{ category }}
{%- endfor %}
.. code-block:: text
:caption: output
- business
- celebrities
-
- lifestyle
- sports
-
- technology
With ``compact``, we can remove those missing categories before the loop.
.. code-block:: liquid2
{% assign categories = pages | map: "category" | compact %}
{% for category in categories %}
- {{ category }}
{% endfor %}
.. code-block:: text
:caption: output
- business
- celebrities
- lifestyle
- sports
- technology
Using the optional argument to ``compact``, we could avoid using ``map`` and create an
array of pages with a ``category`` property, rather than an array of categories.
.. code-block:: liquid2
{% assign pages_with_category = pages | compact: "category" %}
{% for page in pages_with_category %}
- {{ page.category }}
{% endfor %}
.. code-block:: text
:caption: output
- business
- celebrities
- lifestyle
- sports
- technology
concat
------
.. code-block:: text
| concat:
Create a new array by joining one array-like object with another.
.. code-block:: liquid2
{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
{% assign everything = fruits | concat: vegetables %}
{% for item in everything %}
- {{ item }}
{% endfor %}
.. code-block:: text
:caption: output
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
If the input value is not array-like, it will be converted to an array. No conversion is
attempted for the argument value.
.. code-block:: liquid2
{% assign fruits = "apples, oranges, peaches" | split: ", " -%}
{% assign things = "hello" | concat: fruits -%}
{% for item in things -%}
- {{ item }}
{% endfor %}
.. code-block:: text
:caption: output
- h
- e
- l
- l
- o
- apples
- oranges
- peaches
If the input is a nested array, it will be flattened before concatenation. The argument is
not flattened.
.. code-block:: json
:caption: data
{
"a": [
["a", "x"],
["b", ["y", ["z"]]]
],
"b": ["c", "d"]
}
.. code-block:: liquid2
{{ a | concat: b | join: '#' }}
.. code-block:: text
:caption: output
a#x#b#y#z#c#d
date
----
.. code-block:: text
| date:
Format a date and/or time according the the given format string. The input can be a
string, in which case the string will be parsed as a date/time before formatting.
.. code-block:: liquid2
{{ "March 14, 2016" | date: "%b %d, %y" }}
.. code-block:: text
:caption: output
Mar 14, 16
The special ``'now'`` or ``'today'`` input values can be used to get the current
timestamp. ``'today'`` is an alias for ``'now'``. Both include time information.
.. code-block:: liquid2
{{ "now" | date: "%Y-%m-%d %H:%M" }}
.. code-block:: text
:caption: output
2021-12-02 10:17
If the input is undefined, an empty string is returned.
default
-------
.. code-block:: text
| default[:
"
}
.. code-block:: liquid2
:caption: template
{{ greeting }}, {{ username }}
{{ greeting | safe }}, {{ username }}
.. code-block:: text
:caption: output
</p><script>alert("XSS!");</script>, Sally
, Sally
size
----
.. code-block:: text
| size
Return the size of the input object. Works on strings, arrays and hashes.
.. code-block:: liquid2
{{ "Ground control to Major Tom." | size }}
{{ "apples, oranges, peaches, plums" | split: ", " | size }}
.. code-block:: text
:caption: output
28
4
slice
-----
.. code-block:: text
| slice: [, ]
Return a substring or subsequence of the input string or array. The first argument is the
zero-based start index. The second, optional argument is the length of the substring or
sequence, which defaults to ``1``.
.. code-block:: liquid2
{{ "Liquid" | slice: 0 }}
{{ "Liquid" | slice: 2 }}
{{ "Liquid" | slice: 2, 5 }}
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{{ beatles | slice: 1, 2 | join: " " }}
.. code-block:: text
:caption: output
L
q
quid
Paul George
If the first argument is negative, the start index is counted from the end of the
sequence.
.. code-block:: liquid2
{{ "Liquid" | slice: -3 }}
{{ "Liquid" | slice: -3, 2 }}
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{{ beatles | slice: -2, 2 | join: " " }}
.. code-block:: text
:caption: output
u
ui
George Ringo
sort
----
.. code-block:: text
| sort[: ]
Return a copy of the input array with its elements sorted.
.. code-block:: liquid2
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
{{ my_array | sort | join: ", " }}
.. code-block:: text
:caption: output
Sally Snake, giraffe, octopus, zebra
The optional argument is a sort key. If given, it should be the name of a property and the
filter's input should be an array of objects.
.. code-block:: json
:caption: data
{
"collection": {
"products": [
{ "title": "A Shoe", "price": "9.95" },
{ "title": "A Tie", "price": "0.50" },
{ "title": "A Hat", "price": "2.50" }
]
}
}
.. code-block:: liquid2
:caption: template
{% assign products_by_price = collection.products | sort: "price" -%}
{% for product in products_by_price %}
{{ product.title }}
{% endfor %}
.. code-block:: text
:caption: output
A Tie
A Hat
A Shoe
sort_natural
------------
.. code-block:: text
| sort_natural[: ]
Return a copy of the input array with its elements sorted case-insensitively. Array items
will be compared by their string representations, forced to lowercase.
.. code-block:: liquid2
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
{{ my_array | sort_natural | join: ", " }}
.. code-block:: text
:caption: output
giraffe, octopus, Sally Snake, zebra
The optional argument is a sort key. If given, it should be the name of a property and the
filter's input should be an array of objects. Array elements are compared using the
lowercase string representation of that property.
.. code-block:: json
:caption: data
{
"collection": {
"products": [
{ "title": "A Shoe", "company": "Cool Shoes" },
{ "title": "A Tie", "company": "alpha Ties" },
{ "title": "A Hat", "company": "Beta Hats" }
]
}
}
.. code-block:: liquid2
:caption: template
{% assign products_by_company = collection.products | sort_natural: "company" %}
{% for product in products_by_company %}
{{ product.title }}
{% endfor %}
.. code-block:: text
:caption: output
A Tie
A Hat
A Shoe
split
-----
.. code-block:: text
| split:
Return an array of strings that are the input string split on the filter's argument
string.
.. code-block:: liquid2
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{% for member in beatles %}
{{- member }}
{% endfor %}
.. code-block:: text
:caption: output
John
Paul
George
Ringo
If the argument is undefined or an empty string, the input will be split at every
character.
.. code-block:: liquid2
{{ "Hello there" | split: nosuchthing | join: "#" }}
.. code-block:: text
:caption: output
H#e#l#l#o# #t#h#e#r#e
squish
------
**New in version 2.2.0**
.. code-block:: text
| squish
Return the input string with all leading and trailing whitespace removed, and any other
runs of whitespace replaced with a single space.
.. code-block:: liquid2
{{ " Hello, \n\t World! \r\n" | squish }}
.. code-block:: text
:caption: output
Hello, World!
strip
-----
.. code-block:: text
| strip
Return the input string with all leading and trailing whitespace removed. If the input is
not a string, it will be converted to a string before stripping whitespace.
.. code-block:: liquid2
{{ " So much room for activities " | strip }}!
.. code-block:: text
:caption: output
So much room for activities!
strip_html
----------
.. code-block:: text
| strip_html
Return the input string with all HTML tags removed.
.. code-block:: liquid2
{{ "Have you read Ulysses?" | strip_html }}
.. code-block:: text
:caption: output
Have you read Ulysses?
strip_newlines
--------------
.. code-block:: text
| strip_newlines
Return the input string with ``\n`` and ``\r\n`` removed.
.. code-block:: liquid2
{% capture string_with_newlines %}
Hello
there
{% endcapture -%}
{{ string_with_newlines | strip_newlines }}
.. code-block:: text
:caption: output
Hellothere
sum
---
.. code-block:: text
| sum[: ]
Return the sum of all numeric elements in an array.
.. code-block:: liquid2
{% assign array = '1,2,3' | split: ',' -%}
{{ array | sum }}
.. code-block:: text
:caption: output
6
If the optional string argument is given, it is assumed that array items are
hash/dict/mapping-like, and the argument should be the name of a property/key. The values
at ``array[property]`` will be summed.
times
-----
.. code-block:: text
| times:
Return the product of the input number and the argument. If either the input or argument
are not a number, Liquid will try to convert them to a number. If that conversion fails,
``0`` is used instead.
.. code-block:: liquid2
{{ 3 | times: 2 }}
{{ "24" | times: "7" }}
{{ 183.357 | times: 12 }}
.. code-block:: text
:caption: output
6
168
2200.284
truncate
--------
.. code-block:: text
| truncate[: [, ]]
Return a truncated version of the input string. The first argument, length, defaults to
``50``. The second argument defaults to an ellipsis (``...``).
If the length of the input string is less than the given length (first argument), the
input string will be truncated to ``length`` minus the length of the second argument, with
the second argument appended.
.. code-block:: liquid2
{{ "Ground control to Major Tom." | truncate: 20 }}
{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
{{ "Ground control to Major Tom." | truncate: 20, "" }}
.. code-block:: text
:caption: output
Ground control to...
Ground control, and so on
Ground control to Ma
truncatewords
-------------
.. code-block:: text
| truncatewords[: [, ]]
Return the input string truncated to the specified number of words, with the second
argument appended. The number of words (first argument) defaults to ``15``. The second
argument defaults to an ellipsis (``...``).
If the input string already has fewer than the given number of words, it is returned
unchanged.
.. code-block:: liquid2
{{ "Ground control to Major Tom." | truncatewords: 3 }}
{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
.. code-block:: text
:caption: output
Ground control to...
Ground control to--
Ground control to
uniq
----
.. code-block:: text
| uniq[: ]
Return a copy of the input array with duplicate elements removed.
.. code-block:: liquid2
{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " -%}
{{ my_array | uniq | join: ", " }}
.. code-block:: text
:caption: output
ants, bugs, bees
If an argument is given, it should be the name of a property and the filter's input should
be an array of objects.
.. code-block:: json
:caption: data
{
"collection": {
"products": [
{ "title": "A Shoe", "company": "Cool Shoes" },
{ "title": "A Tie", "company": "alpha Ties" },
{ "title": "Another Tie", "company": "alpha Ties" },
{ "title": "A Hat", "company": "Beta Hats" }
]
}
}
.. code-block:: liquid2
:caption: template
{% assign one_product_from_each_company = collections.products | uniq: "company" -%}
{% for product in one_product_from_each_company -%}
- product.title
{% endfor %}
.. code-block:: text
:caption: output
- A Shoe
- A Tie
- A Hat
upcase
------
.. code-block:: text
| upcase
Return the input string with all characters in uppercase.
.. code-block:: liquid2
{{ 'Hello, World!' | upcase }}
.. code-block:: text
:caption: output
HELLO, WORLD!
url_decode
----------
.. code-block:: text
| url_decode
Return the input string with ``%xx`` escapes replaced with their single-character
equivalents. Also replaces ``'+'`` with ``' '``.
.. code-block:: liquid2
{{ "My+email+address+is+bob%40example.com%21" | url_decode }}
.. code-block:: text
:caption: output
My email address is bob@example.com!
url_encode
----------
.. code-block:: text
| url_encode
Return the input string with URL reserved characters %-escaped. Also replaces ``' '`` with
``'+'``.
.. code-block:: liquid2
{{ "My email address is bob@example.com!" | url_encode }}
.. code-block:: text
:caption: output
My+email+address+is+bob%40example.com%21
where
-----
.. code-block:: text
| where: [, ]
Return a copy of the input array including only those objects that have a property, named
with the first argument, equal to a value, given as the second argument. If a second
argument is not given, only elements with the named property that are truthy will be
included.
.. code-block:: json
:caption: data
{
"products": [
{ "title": "Vacuum", "type": "house", "available": true },
{ "title": "Spatula", "type": "kitchen", "available": false },
{ "title": "Television", "type": "lounge", "available": true },
{ "title": "Garlic press", "type": "kitchen", "available": true }
]
}
.. code-block:: liquid2
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 %}
{%- assign available_products = products | where: "available" -%}
Available products:
{% for product in available_products -%}
- {{ product.title }}
{% endfor %}
.. code-block:: text
:caption: output
All products:
- Vacuum
- Spatula
- Television
- Garlic press
Kitchen products:
- Spatula
- Garlic press
Available product:
- Vacuum
- Television
- Garlic press