Liquid Filters

| append

Concatenates two strings and returns the concatenated value.

{{ "/my/fancy/url" | append: ".html" }}

/my/fancy/url.html

append can also be used with variables:

{% assign filename = "/index.html" %}
{{ "website.com" | append: filename }}

website.com/index.html

| prepend

Adds the specified string to the beginning of another string.

{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}

Some fruit: apples, oranges, and bananas

prepend can also be used with variables:

{% assign text = "Some fruit: " %}
{% assign fruit = "apples, oranges, and bananas" %}
{{ text | prepend: fruit }}

Some fruit: apples, oranges, and bananas

| capitalize

Makes the first character of a string capitalized.

{{ "my great title" | capitalize }}

My great title

| downcase

Makes each character in a string lowercase, if it is not already.

{{ "WebinOne" | downcase }}

webinone

| upcase

Makes each character in a string uppercase, if they are not already.

{{ "WebinOne" | upcase }}

WEBINONE

| titlecase

Converts each word in a string to Title Case (capital initial letter for each word).

{{ "This is my sentence" | titlecase }}

This Is My Sentence

| remove

Removes every occurrence of the specified substring from a string.

{{ "I strained to see the train through the rain" | remove: "rain" }}

I sted to see the t through the

| remove_first

Removes only the first occurrence of the specified substring from a string.

{{ "I strained to see the train through the rain" | remove_first: "rain" }}

I sted to see the train through the rain

| replace

Replaces every occurrence of the first argument in a string with the second argument.

{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}

Take your protein pills and put your helmet on

| replace_first

Replaces only the first occurrence of the first argument in a string with the second argument.

{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}

Take your protein pills and put my helmet on

| lstrip

Removes all whitespace (tabs, spaces, and newlines) from the left side of a string. It does not affect spaces between words.

{{ "          So much room for activities!          " | lstrip }}

So much room for activities!

| rstrip

Removes all whitespace (tabs, spaces, and newlines) from the right side of a string. It does not affect spaces between words.

{{ "          So much room for activities!          " | rstrip }}

So much room for activities!

| strip

Removes all whitespace (tabs, spaces, and newlines) from both the left and right sides of a string. It does not affect spaces between words.

{{ "          So much room for activities!          " | strip }}

So much room for activities!

| strip_html

Removes any HTML tags from a string.

{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

Have you read Ulysses?

| slice

Returns a substring of 1 character beginning at the index specified by the first argument.

String indices are numbered starting from 0.

{{ "Liquid" | slice: 2 }}

q

An optional second argument specifies the length of the substring to be returned.

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

| newline_to_br

Replaces every newline (\n) in a string with an HTML line break (<br />).

{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | newline_to_br }}

<br />
Hello<br />
there<br />

| truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.

{{ "Ground control to Major Tom." | truncate: 20 }}

Ground control to...

Custom ellipsis

truncate takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default this is an ellipsis (…), but you can specify a different sequence.

The length of the second argument counts against the number of characters specified by the first argument. For example, if you want to truncate a string to exactly 10 characters, and use a 3-character ellipsis, use 13 for the first argument of truncate, since the ellipsis counts as 3 characters.

{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}

Ground control, and so on

No ellipsis

You can truncate to the exact number of characters specified by the first argument and avoid showing trailing characters by passing a blank string as the second argument:

{{ "Ground control to Major Tom." | truncate: 20, "" }}

Ground control to Ma

| truncatewords

Shortens a string down to the number of words passed as an argument. If the specified number of words is less than the number of words in the string, an ellipsis (…) is appended to the string.

{{ "Ground control to Major Tom." | truncatewords: 3 }}

Ground control to...

Custom ellipsis

truncatewords takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default this is an ellipsis (…), but you can specify a different sequence.

{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}

Ground control to--

No ellipsis

You can avoid showing trailing characters by passing a blank string as the second argument:

{{ "Ground control to Major Tom." | truncatewords: 3, "" }}

Ground control to

| escape

Escapes a string by replacing characters with escape sequences (so that the string can be used in a URL, for example).

{{ "Have you read 'James & the Giant Peach'?" | escape }}

Have you read 'James & the Giant Peach'?

| escape_once

Escapes a string without changing existing escaped entities.

{{ "1 < 2 & 3" | escape_once }}

1 < 2 & 3

Example with already escaped entities:

{{ "1 < 2 & 3" | escape_once }}

1 < 2 & 3

| unescape

Unescapes a string by replacing escaped sequences with unescaped characters (so you can convert an escaped string back to its intended form).

{{ "Have you read 'James & the Giant Peach'?" | unescape }}

Have you read 'James & the Giant Peach'?

| url_decode

Decodes a string that has been encoded as a URL or by url_encode.

{{ "%27Stop%21%27+said+Fred" | url_decode }}

'Stop!' said Fred

| url_encode

Converts any URL-unsafe characters in a string into percent-encoded characters.

{{ "email: john@liquid.com" | url_encode }}

email%3A+john%40liquid.com

| default

Allows you to specify a fallback in case a value doesn’t exist. default will show its value if the left side is nil, false, or empty.

In this example, product_price is not defined, so the default value is used.

{{ product_price | default: 2.99 }}

2.99

| size

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

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

28

With an array:

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

4

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

{% if this.items.size > 10 %}
  There are more than 10 items.
{% endif %}

| split

Divides a string into an array using the argument as a separator. split is commonly used to convert comma-separated items from a string to an array.

{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{% for member in beatles %}
  {{ member }}
{% endfor %}

John Paul George Ringo

| 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

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

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

| first

Returns the first item of an array.

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

zebra

Converting a string to an array:

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

Ground

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.

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

tiger

Converting a string to an array:

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

Tom.

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

| uniq

Removes any duplicate elements in an array.

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

ants, bugs, bees

| compact

Removes any null values from an array.

For this example, assume this.items is an array of website items that have an attribute called category. If we map those categories to an array, some of the array items might be null if any items do not have a category attribute.

{% assign site_items = this.items | map: "category" %}

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

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

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

{% assign site_items = this.items | map: "category" | compact %}

{% for category in site_items %}
- {{ category }}
{% 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

| map

Creates an array of values by extracting the values of a named property from another object.

In this example, assume the object this.items contains website items that include a property called 'category'. Using assign with the map filter creates a variable that contains only the values of the 'category' properties for everything within the this.items object.

{% assign all_categories = this.items | map: "category" %}

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

- business
- celebrities
- lifestyle
- sports
- technology

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

28

With an array:

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

4

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

{% if this.items.size > 10 %}
  There are more than 10 items.
{% endif %}

| plus

Adds a number to another number.

{{ 4 | plus: 2 }}

6

A plus with a float (a number with a decimal in it):

{{ 183.357 | plus: 12 }}

195.357

| minus

Subtracts a number from another number.

{{ 4 | minus: 2 }}

2

A minus with a float (a number with a decimal in it):

{{ 183.357 | minus: 12 }}

171.357

| times

Multiplies a number by another number.

{{ 3 | times: 2 }}

6

A times with a float (a number with a decimal in it):

{{ 183.357 | times: 12 }}

2200.284

| divided_by

Divides a number by another number.

The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.

{{ 16 | divided_by: 4 }}

4

Example of rounding down:

{{ 5 | divided_by: 3 }}

1

Controlling rounding

divided_by produces a result of the same type as the divisor — that is, if you divide by an integer, the result will be an integer. If you divide by a float (a number with a decimal in it), the result will be a float.

For example, here the divisor is an integer:

{{ 20 | divided_by: 7 }}

2

Here it is a float:

{{ 20 | divided_by: 7.0 }}

2.857142857142857

Changing variable types

You might want to use a variable as a divisor, in which case you can’t simply add .0 to convert it to a float. In these cases, you can assign a version of your variable converted to a float using the times filter.

In this example, we’re dividing by a variable that contains an integer, so we get an integer:

{% assign my_integer = 7 %}
{{ 20 | divided_by: my_integer }}

2

Here, we multiply the variable by 1.0 to get a float, then divide by the float instead:

{% assign my_integer = 7 %}
{% assign my_float = my_integer | times: 1.0 %}
{{ 20 | divided_by: my_float }}

2.857142857142857

| modulo

Returns the remainder of a division operation.

{{ 3 | modulo: 2 }}

1

Example with rounding:

{{ 24 | modulo: 7 }}

3

A modulo with a float (a number with a decimal in it):

{{ 183.357 | modulo: 12 }}

3.357

| round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.

{{ 1.2 | round }}

1

Rounding up:

{{ 2.7 | round }}

3

A round with a float (a number with a decimal in it):

{{ 183.357 | round: 2 }}

183.36

| ceil

Rounds the input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.

{{ 1.2 | ceil }}

2

Here the input value is a string:

{{ "3.5" | ceil }}

4

| floor

Rounds the input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.

{{ 1.2 | floor }}

1

Here the input value is a string:

{{ "3.5" | floor }}

3

| date

Converts a timestamp into another date format or a formatted date string based on the syntax provided. The format for this syntax is similar to strftime.

For example; if outputting the site's time using the "now" keyword, the default format is as below:

{{ "now" | date }}

27-Feb-2020

Or to reformat the date using 'strftime' syntax.

{{ "now" | date: "%Y-%m-%d %H:%M" }}

2019-09-19 17:48

date also works on strings if they contain well-formatted dates:

{{ "March 14, 2016" | date: "%b %d, %y" }}

Mar 14, 16

As well as the date filter being able to recogonize well formatted dates, it will also format 'seconds since 1970' back into a date.

For example; we have calculated a difference between today's date and 14 days ago in seconds (1209600) and now want to display that result as a date string:

{% assign dateDiff = "27-Feb-2020" | date: "%s" | minus: 1209600 %}
{{ dateDiff | date: "%v %r" }}

Thursday, February 13, 2020 12:00:00 AM

| format_date

Converts a timestamp into a formatted date string based on the syntax provided. The format for this syntax is as per the .NET Time Format (very similar to the BC implementation).

For example; if outputting the site's time using the "now" keyword, a date format can be given:

{{ "now" | format_date: "yyyy-MM-dd H:mm" }}

2019-09-19 17:48

format_date also works on strings if they contain well-formatted dates:

{{ "March 14, 2016" | format_date: "MMM dd, y" }}

Mar 14, 16

As well as the format_date filter being able to recogonize well formatted dates, it will also format 'seconds since 1970' back into a date (although it cannot calculate the 'seconds since 1970' directly - we'll use the above date filter for this).

For example; we have calculated a difference between today's date and 14 days ago in seconds (1209600) and now want to display that result as a date string:

{% assign dateDiff = "27-Feb-2020" | date: "%s" | minus: 1209600 %} <!-- note: we're using `date` filter here -->
{{ dateDiff | format_date: "dddd, MMMM dd, yyyy hh:mm:ss tt" }}

Thursday, February 13, 2020 12:00:00 AM

| datetime

Add the time component to the site's date:

{{ "now" | datetime }}

27-Feb-2020 4:46 AM

| date_utc

Converts a date to UTC (assuming that the date is always given in the site’s timezone)

{{ "now" | date_utc }}

2020-02-27 10:46:21Z

| date_add

Filters a given date time object (or a string convertible to a date time object) and adds (or subtracts) an amount from a defined date part based on the additional arguments passed, for example:

{% assign myDate = "2016-06-15T12:30:30.400" %}
{{ myDate | date_add: 7, "day" }}

2016-06-22 12:30:30Z

The first argument is the amount - an integer/number or a string convertible to an integer/number representing the amount of date or time units to add (if positive) or to subtract (if negative) from the input date time object

The second argument is the datePart - a string representing the date or time parts to be added or subtracted.
The possible values are:

• "year"
• "month"
• "day"
• "hour"
• "minute"
• "second"
• "millisecond"

If one of the arguments is of an incompatible type or value, the filter will not alter the input.

| domain_number_format

Formats a number to a string based on standard cultural number formating from the 'Currency and Format' settings of the current domain (void of any currency related attributes).

If liquid parsing is outside of the domain scope it uses the default domain settings, else the value is not changed.

For example, if the item price is set as 49990.9455 and the current domain is configured for United States:

{{ this.Price | domain_number_format }}

49,990.95

| set_number_format

Formats a number to a string based on standard cultural number formating from the 'Currency and Format' settings of the specified domain (void of any currency related attributes).
The domain settings to use are specified via the additional argument provided with the filter, which is the system ID, or Name, of the 'Currency and Format' item saved against the required domain.

If liquid parsing is outside of the domain scope it uses the default domain settings, else the value is not changed.

For example, if the item price is set as 49990.9455 and the required domain is configured for Denmark:

{{ this.Price | set_number_format: "[formatSettingIDorName]" }}

49.990,95

| domain_money_format

Formats a number to a string based on standard cultural monetary formating from the 'Currency and Format' settings of the current domain.

If liquid parsing is outside of the domain scope it uses the default domain settings, else the value is not changed.

For example, if the item price is set as 49990.9455 and the current domain is configured for United States:

{{ this.Price | domain_money_format }}

$49,990.95

| set_money_format

Formats a number to a string based on standard cultural monetary formating from the 'Currency and Format' settings of the specified domain.
The domain settings to use are specified via the additional argument provided with the filter, which is the system ID, or Name, of the 'Currency and Format' item saved against the required domain.

If liquid parsing is outside of the domain scope it uses the default domain settings, else the value is not changed.

For example, if the item price is set as 49990.9455 and the required domain is configured for Denmark:

{{ this.Price | set_money_format: "[formatSettingIDorName]" }}

49.990,95 $