# Liquid - Filters

Last edit: Aug 26, 2021

## abs

Returns the absolute value of a number.

#### Input

``````
{{ -17 | abs }}

``````

#### Output

``````17
``````

#### Input

``````
{{ 4 | abs }}

``````

#### Output

``````4
``````

`abs` will also work on a string if the string only contains a number.

#### Input

``````
{{ "-19.86" | abs }}

``````

#### Output

``````19.86
``````

## append

Concatenates two strings and returns the concatenated value.

#### Input

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

``````

#### Output

``````hello.html
``````

`append` can also be used with variables:

#### Input

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

``````

#### Output

``````
website.com/index.html
``````

`append` can be used with a number, it will return a string:

#### Input

``````
{{ 3 | append: ' stooges' }}

``````

#### Output

``````3 stooges
``````

## at_least

Limits a number to a minimum value.

#### Input

``````
{{ 4 | at_least: 5 }}

``````

#### Output

``````5
``````

#### Input

``````
{{ 4 | at_least: 3 }}

``````

#### Output

``````4
``````

## at_most

Limits a number to a maximum value.

#### Input

``````
{{ 4 | at_most: 5 }}

``````

#### Output

``````4
``````

#### Input

``````
{{ 4 | at_most: 3 }}

``````

#### Output

``````3
``````

## capitalize

Makes the first character of a string capitalized.

#### Input

``````
{{ "title" | capitalize }}

``````

#### Output

``````Title
``````

`capitalize` only capitalizes the first character of the string, so later words are not affected:

#### Input

``````
{{ "my great title" | capitalize }}

``````

#### Output

``````My great title
``````

## ceil

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

#### Input

``````
{{ 1.2 | ceil }}

``````

#### Output

``````2
``````

#### Input

``````
{{ 2.0 | ceil }}

``````

#### Output

``````2
``````

#### Input

``````
{{ 183.357 | ceil }}

``````

#### Output

``````184
``````

Here the input value is a string:

#### Input

``````
{{ "3.5" | ceil }}

``````

#### Output

``````4
``````

## concat

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

#### Input

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

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

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

``````

#### Output

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

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

#### Input

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

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

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

``````

#### Output

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

## date

Converts a timestamp into another date format. The format for this syntax is the same as `strftime`. You can use the standard date formatting for UNIX. Available directives for time and date are listed here.

#### Input

``````
{{ article.published_at | date: "%a, %b %d, %y" }}

``````

#### Output

``````Fri, Jul 17, 15
``````

#### Input

``````
{{ article.published_at | date: "%Y" }}

``````

#### Output

``````2015
``````

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

#### Input

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

``````

#### Output

``````Mar 14, 16
``````

To get the current time, pass the special word `"now"` (or `"today"`) to date:

#### Input

``````
This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

``````

#### Output

``````This page was last updated at 2021-10-18 10:42.
``````

Note that the value will be the current time of when the page was last generated from the template, not when the page is presented to a user if caching or static site generation is involved.

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

#### Input

``````
{{ product_price | default: 2.99 }}

``````

#### Output

``````2.99
``````

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

#### Input

``````
{% assign product_price = 4.99 %}
{{ product_price | default: 2.99 }}

``````

#### Output

``````
4.99
``````

In this example, `product_price` is empty, so the default value is used.

#### Input

``````
{% assign product_price = "" %}
{{ product_price | default: 2.99 }}

``````

#### Output

``````
2.99
``````

To allow variables to return `false` instead of the default value, you can use the `allow_false` parameter.

#### Input

``````
{{ settings.flag | default: true, allow_false: true }}

``````

#### Output

``````<!-- If settings.flag is false -->
false
``````

## divided_by

Divides a number by the specified number.

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

#### Input

``````
{{ 16 | divided_by: 4 }}

``````

#### Output

``````4
``````

#### Input

``````
{{ 5 | divided_by: 3 }}

``````

#### Output

``````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:

#### Input

``````
{{ 20 | divided_by: 7 }}

``````

#### Output

``````2
``````

Here it is a float:

#### Input

``````
{{ 20 | divided_by: 7.0 }}

``````

#### Output

``````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, you’re dividing by a variable that contains an integer, so you get an integer:

#### Input

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

``````

#### Output

``````
2
``````

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

#### Input

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

``````

#### Output

``````

2.857142857142857
``````

## downcase

Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.

#### Input

``````
{{ "Parker Moore" | downcase }}

``````

#### Output

``````parker moore
``````

#### Input

``````
{{ "apple" | downcase }}

``````

#### Output

``````apple
``````

## escape

Escapes a string by replacing characters with escape sequences (so that the string can be used in a URL, for example). It doesn’t change strings that don’t have anything to escape.

#### Input

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

``````

#### Output

``````Have you read 'James &amp; the Giant Peach'?
``````

#### Input

``````
{{ "Nikola Tesla" | escape }}

``````

#### Output

``````Nikola Tesla
``````

## first Returns the first item of an array. #### Input ```liquid {% assign my_array = "apples, oranges, peaches, plums" | split: ", " %} {{ my_array.first }}

#### Output

``````
apples
``````

#### Input

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

``````

#### Output

``````
zebra
``````

## floor

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

#### Input

``````
{{ 1.2 | floor }}

``````

#### Output

``````1
``````

#### Input

``````
{{ 2.0 | floor }}

``````

#### Output

``````2
``````

#### Input

``````
{{ 183.357 | floor }}

``````

#### Output

``````183
``````

Here the input value is a string:

#### Input

``````
{{ "3.5" | floor }}

``````

#### Output

``````3
``````

## join

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

#### Input

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

{{ beatles | join: " and " }}

``````

#### Output

``````
John and Paul and George and Ringo
``````

## last

Returns the last item of an array.

#### Input

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

``````

#### Output

``````
plums
``````

#### Input

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

``````

#### Output

``````
tiger
``````

## lstrip

Removes all whitespaces (tabs, spaces, and newlines) from the beginning of a string. The filter does not affect spaces between words.

#### Input

``````
A sentence before. {{ "          So much room for activities!          " | lstrip }} A sentence after.

``````

#### Output

``````A sentence before. So much room for activities!           A sentence after.
``````

## map

Important

We have overwritten the map filter so it will not work in the standard way. Visit the reference for the platformOS map filter to learn more.

## minus

Subtracts a number from another number.

#### Input

``````
{{ 4 | minus: 2 }}

``````

#### Output

``````2
``````

#### Input

``````
{{ 16 | minus: 4 }}

``````

#### Output

``````12
``````

#### Input

``````
{{ 183.357 | minus: 12 }}

``````

#### Output

``````171.357
``````

## modulo

Returns the remainder of a division operation.

#### Input

``````
{{ 3 | modulo: 2 }}

``````

#### Output

``````1
``````

#### Input

``````
{{ 24 | modulo: 7 }}

``````

#### Output

``````3
``````

#### Input

``````
{{ 183.357 | modulo: 12 }}

``````

#### Output

``````3.357
``````

## newline_to_br

Replaces every newline (`\n`) with an HTML line break (`<br>`).

#### Input

``````
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | newline_to_br }}

``````

#### Output

``````

Hello
there

``````

## plus

Adds a number to another number.

#### Input

``````
{{ 4 | plus: 2 }}

``````

#### Output

``````6
``````

#### Input

``````
{{ 16 | plus: 4 }}

``````

#### Output

``````20
``````

#### Input

``````
{{ 183.357 | plus: 12 }}

``````

#### Output

``````195.357
``````

## prepend

Adds the specified string to the beginning of another string.

#### Input

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

``````

#### Output

``````Some fruit: apples, oranges, and bananas
``````

You can also prepend variables:

#### Input

``````
{% assign url = "example.com" %}
{{ "/index.html" | prepend: url }}

``````

#### Output

``````
example.com/index.html
``````

## remove

Removes every occurrence of the specified substring from a string.

#### Input

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

``````

#### Output

``````I sted to see the t through the
``````

## remove_first

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

#### Input

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

``````

#### Output

``````I sted to see the train through the rain
``````

## replace

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

#### Input

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

``````

#### Output

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

#### Input

``````
{% assign my_string = "Take my protein pills and put my helmet on" %}
{{ my_string | replace_first: "my", "your" }}

``````

#### Output

``````
Take your protein pills and put my helmet on
``````

## reverse

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

#### Input

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

``````

#### Output

``````
plums, peaches, oranges, apples
``````

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

#### Input

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

``````

#### Output

``````.moT rojaM ot lortnoc dnuorG
``````

## round

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

#### Input

``````
{{ 1.2 | round }}

``````

#### Output

``````1
``````

#### Input

``````
{{ 2.7 | round }}

``````

#### Output

``````3
``````

#### Input

``````
{{ 183.357 | round: 2 }}

``````

#### Output

``````183.36
``````

## rstrip

Removes all whitespace (tabs, spaces, and newlines) from the right side of a string.

#### Input

``````
A sentence before. {{ "          So much room for activities!          " | rstrip }} A sentence after.

``````

#### Output

``````A sentence before.           So much room for activities! A sentence after.
``````

## size

Returns the number of characters in a string, the number of items in an array, or the number of bytes needed to store the integer in memory. `size` can also be used with dot notation (for example, 42). This allows you to use size inside tags such as conditionals.

#### Input

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

``````

#### Output

``````28
``````

#### Input

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

``````

#### Output

``````
4
``````

Using dot notation:

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

``````

## slice

Returns a substring of 1 character beginning at the index specified by the argument passed in. An optional second argument specifies the length of the substring to be returned.

String indices are numbered starting from 0.

#### Input

``````
{{ "Liquid" | slice: 0 }}

``````

#### Output

``````L
``````

#### Input

``````
{{ "Liquid" | slice: 2 }}

``````

#### Output

``````q
``````

#### Input

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

``````

#### Output

``````quid
``````

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

#### Input

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

``````

#### Output

``````ui
``````

## sort

Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive, meaning all capitalized strings will come before any lowercase strings.

#### Input

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

``````

#### Output

``````
Sally Snake, giraffe, octopus, zebra
``````

## sort_natural

Sorts items in an array by a property of an item in the array. The order of the sorted array is case-insensitive.

#### Input

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

``````

#### Output

``````
giraffe, octopus, Sally Snake, zebra
``````

## split

Divides an input 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.

#### Input

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

``````

#### Output

``````

John

Paul

George

Ringo

``````

## strip

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

#### Input

``````
A sentence before. {{ "          So much room for activities!          " | strip }} A sentence after.

``````

#### Output

``````A sentence before. So much room for activities! A sentence after.
``````

## strip_html

Removes any HTML tags from a string.

#### Input

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

``````

#### Output

``````
``````

## strip_newlines

Removes any newline characters (line breaks) from a string.

#### Input

``````
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | strip_newlines }}

``````

#### Output

``````
Hellothere
``````

## times

Multiplies a number by another number.

#### Input

``````
{{ 3 | times: 2 }}

``````

#### Output

``````6
``````

#### Input

``````
{{ 24 | times: 7 }}

``````

#### Output

``````168
``````

#### Input

``````
{{ 183.357 | times: 12 }}

``````

#### Output

``````2200.284
``````

## truncate

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

#### Input

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

``````

#### Output

``````Ground control to...
``````

### Custom ellipsis

`truncate` takes an optional second parameter 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 parameter counts against the number of characters specified by the first parameter.
For example, if you want to truncate a string to exactly 10 characters, and use a 3-character ellipsis, use 13 for the first parameter of `truncate`, since the ellipsis counts as 3 characters.

#### Input

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

``````

#### Output

``````Ground control, and so on
``````

### No ellipsis

You can truncate to the exact number of characters specified by the first parameter and show no trailing characters by passing a blank string as the second parameter:

#### Input

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

``````

#### Output

``````Ground control to Ma
``````

## truncatewords

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

#### Input

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

``````

#### Output

``````Ground control to...
``````

### Custom ellipsis

`truncatewords` takes an optional second parameter 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.

#### Input

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

``````

#### Output

``````Ground control to--
``````

### No ellipsis

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

#### Input

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

``````

#### Output

``````Ground control to
``````

## uniq

Removes any duplicate elements in an array.

#### Input

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

``````

#### Output

``````
ants, bugs, bees
``````

## upcase

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.

#### Input

``````
{{ "Parker Moore" | upcase }}

``````

#### Output

``````PARKER MOORE
``````

#### Input

``````
{{ "TESLA" | upcase }}

``````

#### Output

``````TESLA
``````

## url_decode

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

#### Input

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

``````

#### Output

``````'Stop!' said Fred
``````

## url_encode

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

#### Input

``````
{{ "john@liquid.com" | url_encode }}

``````

#### Output

``````john%40liquid.com
``````

#### Input

``````
{{ "Nikola Tesla" | url_encode }}

``````

#### Output

``````Nikola+Tesla
``````