Liquid filters for encoding, decoding, and other utility operations.
If the input is null, an empty string, or invalid (object.is_valid == false), return the default value. Otherwise returns the input. Note that if the input is the boolean value false, this will return false.
{%- var greeting = "" -%}
{{- greeting | default: "hello" }} world
{%- set greeting = "goodbye" -%}
{{- greeting | default: "hello" }} worldhello world goodbye world
{% var page = request.query_params['page'] | to_int | default: 1 %}String default
{%- var greeting = "" -%}
{{- greeting | default: "hello" }} world
{%- set greeting = "goodbye" -%}
{{- greeting | default: "hello" }} worldhello world goodbye world
Output a default value when the input string is null or empty.
Numeric default (e.g. query parameter)
{% var page = request.query_params['page'] | to_int | default: 1 %}Provide a default value for a numeric query parameter when missing or invalid. The to_int filter is used to convert the query parameter to a number if it is not already a number.
Default for an optional custom field
{{ item['headline'].value | default: "Untitled" | escape }}Take .value so default sees a string (or an invalid/empty field), then escape for HTML. Do not pipe a field’s default output through default as if it were a plain string, and do not use default on entity.title.
Default with filters in a chain
{{ classname_prefix | strip | default: 'fallback-' | append: entity.name.value | classname }}Combine default with other filters; filters are applied in the order they are listed.
Convert a query parameter to boolean
{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}Sets the show_buttons variable to true unless the show_btns query parameter is present and set to false.
Convert a query parameter to integer
{% var limit = request.query_params['limit'] | to_int | default: 20 %}Sets the limit variable to 20 unless the limit query parameter is present and set to a valid integer.
Convert a query parameter to number
{% var average = request.query_params['average'] | to_number | default: 2.5 %}Sets the average variable to 2.5 unless the average query parameter is present and set to a valid number.
Returns the input formatted as a string using the provided format string. There are three types of objects that can be formatted, and each type uses its own format strings. If the input object is a string that can be converted to a date, it will be converted to a date before formatting. Otherwise if the input object is a string that can be converted to a number, it will be converted to a number before formatting:
Numbers - Require a valid standard or custom .NET numeric format string. This is identical to using the format_number filter on a number.
Dates - Require a valid standard or custom .NET date format.
Time Diffs - Require a valid standard or custom .NET TimeSpan format.
{
"null": {{ null | for_json }},
"date": {{ request.date | json_encode }},
"true": {{ true | json_encode }},
"3": {{ 3 | json_encode }},
"-4.2": {{ -4.2 | json_encode }},
"string": {{ 'Liquid is "cool"' | json_encode -}}
}{
"null": null,
"date": "2009-06-15T13:45:30.0000000Z",
"true": true,
"3": 3,
"-4.2": -4.2,
"string": "Liquid is \"cool\""
}{% var startdate = '2009-09-09 14:00:00Z' | date | to_timezone: 'America/New_York' %}
{% var enddate = '2009-09-10 17:32:00Z' | date | to_timezone: 'America/New_York' %}
{% var diff = startdate | time_diff: enddate %}Format a time diff as a constant time span string
{{ diff | format: "c" }}-1.03:32:00
Formats a time diff as a constant time span string (c = constant time span).
Format a time diff as a compact time span string
{{ diff | format: "g" }}-1:3:32:00
Format a time diff using a custom .NET TimeSpan format string
{% if diff.total_seconds < 0 %}-{% endif %}{{ diff | format: "d' days, 'h' hours, and 'm' minutes'" }}-1 days, 3 hours, and 32 minutes
Formats a time diff using a custom .NET TimeSpan format string. Since custom .NET TimeSpan format strings do not have a way to output the minus sign for negative time spans, you have to check for negative time spans separately.
Format a number with 2 decimal places and group separators
{{ -1234.5678 | format_number: 'N2' }}-1,234.57
Uses .NET-style numeric format strings (N2 = number with 2 decimal places and group separator).
Format a number with 4 decimal places and no group separators
{{55555.9 | format_number: "F4"}}55555.9000
Uses .NET-style numeric format strings (F4 = number with 4 decimal places).
Format a number with no decimal places
{{5.9 | format_number: "F0"}}6
Uses .NET-style numeric format strings (F0 = number with no decimal places). The number is rounded as necessary to fit the format string. If you want to round down to the nearest integer, you can use the floor filter instead of the format_number filter.
Format a percent
{{ 0.333333 | format: 'P1' }}33.3%
Uses .NET-style percentage format strings (P1 = percentage with 1 decimal place).
Format an integer with leading zeros
{{ 12345 | format: 'D8' }}00012345
Uses .NET-style decimal format strings (D8 = decimal with 8 digits). The decimal format string is only valid for integers.
Format a number with a custom numeric format string
{{ 1234567890 | format: '(###) ###-####' }}
{{ 42 | format: 'My Number = #' }}(123) 456-7890 My Number = 42
Outputs two numbers formatted with different custom .NET-style format strings.
{% var sep9 = '2009-09-09 14:00:00Z' | date | to_timezone: 'America/New_York' %}Format a date as a short date string
{{sep9 | format: "d"}}9/9/2009
Formats a date as a short date string (d = short date).
Format a date as a short date string with the time
{{sep9 | format: "g"}}9/9/2009 10:00 AM
Formats a date as a short date string with the time (g = short date with time).
Format a date as a long date string
{{sep9 | format: "D"}}Sunday, September 9, 2009
Formats a date as a long date string (D = long date).
Format a date as a long date string with the time
{{sep9 | format: "f"}}Sunday, September 9, 2009 10:00 AM
Formats a date as a long date string with the time (f = long date with time).
Format a date according to the ISO 8601 standard
{{sep9 | format: "o"}}9/9/2009 2:00:00 PM
Formats a date according to the ISO 8601 standard (o = round trip format with offset).
Format a date as a sortable date string
{{sep9 | format: "u"}}9/9/2009 2:00:00 PM
Formats a date as a sortable date string (u = universal sortable date in UTC timezone).
Format a date to a long date string using a custom date format string
{{sep9 | format: "MMMM dd, yyyy 'at' HH:mm:ss"}}September 09, 2009 at 10:00:00
Formats a date using a custom .NET date format string.
Format a date to a short date string using a custom date format string
{{sep9 | format: "hh:mm tt 'on' MM-dd-yy"}}10:00 AM on 09-09-09
Formats a date using a custom .NET date format string.
You can also use the date filter to format a date
{{sep9 | date: "hh:mm tt 'on' MM-dd-yy"}}10:00 AM on 09-09-09
The date and format filters use the same format strings for dates, but the date filter can only be used to format dates while the format filter can also be used to format numbers and time diffs.
Format a date
{% var d = '2009-09-09 14:00:00Z' | date | to_timezone: 'America/New_York' %}
{{ d | format: "d" }}9/9/2009
Use the format filter with .NET date format strings (e.g. "d" for short date).
Format a number
{{ -1234.5678 | format_number: 'N2' }}-1,234.57
Use the format_number filter with .NET numeric format strings (e.g. N2 for number with 2 decimals and group separator).
Returns a json-like representation of the current object up to depth layers deep (max 10). Will not load new information from the server unless forceLoad is set to true. Useful during template development and debugging, but do not rely on the result of the inspect tag for your live site.
Inspect up to 5 layers deep, but do not load any new data from the server
{{entity.what_is_this | inspect: 5}}Inspect up to 3 layers deep, and load any necessary data from the server
{{variable | inspect: 3, true}}Returns a string identifying the type of the input object. If generic_object_check is true, will return "object" for most objects. If generic_object_check is false or unspecified, will return the value of {{ object.object_type }} for objects with an object_type property.
The most common object_type values are: null, object, string, boolean, date, number, list, other specific object types (article, blog_post, etc...)
{%- blog_post post = "post" -%}
{{- post | object_type -}}
{{- post | object_type: true }}blog_post object
Returns a random value. Can behave differently depending on both the type of input and on the arguments supplied. Unless prevent_cache is false, the rand filter will prevent the page from being fast-cached. Note: the rand filter should NOT be considered cryptographically secure - do not use in places where cryptographic security is a requirement (ie: do not use to generate random passwords).
This filter behaves differently depending on the type of input supplied:
Number - If the input is an integer and length is 1, returns a new integer between 1 and the input value. If the input is an integer and length is greater than 1, returns a new list of length numbers between 1 and the input value. If allow_repeats is false, the list returned will be unique. This may result in a list with fewer than length items if the input is less than length.
String - If the input is a string, returns a new random string with length characters, where each character comes directly from the input. If allow_repeats is false, no characters from the input will be used more than once (although any character repeated in the input may be repeated up to the same number of times in the resulting string) - which may result in a string shorter than length if the input string is shorter than length.
List - If the input is a list or list-like object and length is 1, returns a random object from the list. If the input is a list or list-like object and length is greater than 1, returns a new random list of length items from the input list. If allow_repeats is false, no items from the input will be used more than once (although any repeated items in the input may be repeated up to the same number of times in the resulting list) - which may result in a list with fewer than length items if the input list has fewer than length items.
One random item from an existing list (prevents fast-caching)
{%- blog_posts posts = start:1 limit:10 -%}
{%- var randompost = posts | rand -%}
<p>Random pick: {{ randompost.linked_title }}</p>Get a random item from an existing list. Every time the page is loaded a new random item will be chosen.
One random item from an existing list (allows fast-caching)
{%- blog_posts posts = start:1 limit:10 -%}
{%- var randompost = posts | rand:1, false, false -%}
<p>Fast-Cached Random pick: {{ randompost.linked_title }}</p>Get a random item from an existing list and allow the page to be fast-cached. Subsequent pageloads will have the same random item chosen until the cache expires unless there is something else on the page that prevents fast-caching.
Improved: Fetch only one item from the database
{%- blog_posts intermediate = limit:1 sort_by:'random' cache_random:true -%}
{%- var randompost = intermediate | first -%}
<p>Today's pick: {{ randompost.linked_title }}</p>Functionally equivalent to the previous example, but only one item has to be fetched from the database. With the cache_random:true argument the result may be fast-cached and can be reused for subsequent pageloads and without the cache_random argument the page will not able to be fast-cached.
Multiple random items, no duplicates
{%- var numbers = (10..20) -%}
{%- var randomitems = numbers | rand:3, false -%}
{{- randomitems | join:' ' -}}Get 3 random numbers between 10 and 20 without repeats and outputs them as a space-separated list. Because the third argument is not provided the page will not be fast-cached and every pageload will have a new set of random numbers.
Multiple random numbers with duplicates allowed
{%- var rolls = 6 | rand: 4 -%}
<p>Dice rolls: {{ rolls | join: ', ' }}</p>Get 4 random numbers between 1 and 6 and output them as a comma-separated list. Because the second argument is not provided, duplicates are allowed. Because the third argument is not provided, the page will not be fast-cached and every pageload will have a new set of random numbers.
Multiple random numbers with duplicates allowed and fast-cacheable
{%- var rolls = 6 | rand: 4, true, false -%}
<p>Dice rolls: {{ rolls | join: ', ' }}</p>Functionally identical to the previous example except the page may be fast-cached so that future pageloads are significantly faster, but may include the same set of random numbers until the cache expires.
Multiple unique random numbers
{%- var picks = 10 | rand: 4, false -%}
<p>Unique picks: {{ picks | join: ' ' }}</p>Gets 4 unique random numbers between 1 and 10 and outputs them as a space-separated list. Because the third argument is not provided, the page will not be fast-cached and every pageload will have a new set of random numbers.
Single random number between 0 and 10
{{ 11 | rand: 1 | minus: 1 }}To get a random number starting with 0 we need to subtract 1 from the result. To allow the page to be fast-cached: Specify either true or false for the second argument (it doesn't matter which for this example) and specify false for the third argument.
Random character from a string (cache in page)
{{ "aaabcdeeefghjkmnpqrstuuuvwxyz123456789-_" | rand }}Gets a single random character from the set of characters in the string. In this example, the set of characters includes lowercase letters, numbers, and the hyphen and underscore characters with some characters excluded and some repeated to increase their probability of being chosen.
Random alphanumeric string
{{ "abcdefghijklmnopqrstuvwxyz0123456789" | rand: 10 }}Pick 10 random characters from the set, with duplicates allowed. Because the third argument is not provided, the page will not be fast-cached and every pageload will have a new set of random characters.
Random alphanumeric string without duplciates
{{ "abcdefghijklmnopqrstuvwxyz0123456789-----_____" | rand: 10, false }}Pick 10 random characters from the set, with no duplicates allowed. However, because the set itself contains 5 hyphens and 5 underscores the result may also contain up to 5 hyphens and 5 underscores. Because the third argument is provided as false, the page will not be fast-cached and every pageload will have a new set of random characters.
Converts the input to true or false if possible. If not returns null.
{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}Convert a query parameter to boolean
{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}Sets the show_buttons variable to true unless the show_btns query parameter is present and set to false.
Convert a query parameter to integer
{% var limit = request.query_params['limit'] | to_int | default: 20 %}Sets the limit variable to 20 unless the limit query parameter is present and set to a valid integer.
Convert a query parameter to number
{% var average = request.query_params['average'] | to_number | default: 2.5 %}Sets the average variable to 2.5 unless the average query parameter is present and set to a valid number.
Converts the input to an integer.
If the input is null, returns 0. If the input is non-null and cannot be convert to an integer, returns null.
{% var page = request.query_params['page'] | to_int | default: 1 %}{% var limit = request.query_params['limit'] | default: 20 | to_int %}Convert a query parameter to boolean
{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}Sets the show_buttons variable to true unless the show_btns query parameter is present and set to false.
Convert a query parameter to integer
{% var limit = request.query_params['limit'] | to_int | default: 20 %}Sets the limit variable to 20 unless the limit query parameter is present and set to a valid integer.
Convert a query parameter to number
{% var average = request.query_params['average'] | to_number | default: 2.5 %}Sets the average variable to 2.5 unless the average query parameter is present and set to a valid number.
This filter has been deprecated. You should use the json_encode filter instead. Encode a string to be used output as JSON. Unlike json_encode, if the string is null this will return an empty string instead.
{
"null": {{ null | for_json }},
"date": {{ request.date | json_encode }},
"true": {{ true | json_encode }},
"3": {{ 3 | json_encode }},
"-4.2": {{ -4.2 | json_encode }},
"string": {{ 'Liquid is "cool"' | json_encode -}}
}{
"null": null,
"date": "2009-06-15T13:45:30.0000000Z",
"true": true,
"3": 3,
"-4.2": -4.2,
"string": "Liquid is \"cool\""
}{"something": {{'with "value"' | for_json}} }
{"something": {{null | for_json}} }{"something": "with \"value\""}
{"something": }The for_json filter works for input with valid values
{"something": {{'with "value"' | for_json}} }{"something": "with \"value\""}The for_json filter does not produce output if the input is null
{"something": {{null | for_json}} }{"something": }You can get away with the for_json filter by manually handling null/invalid values
{"something": {% if variable is_valid %}{{variable | for_json}}{% else %}null{% endif %} }The entire for_json filter is deprecated because the json_encode filter handles this and other uses cases more robustly
{"something": {{variable | json_encode }} }Converts the input to a number.
If the input is null, returns 0. If the input is non-null and cannot be convert to an integer, returns null.
{% var average = request.query_params['average'] | default: 2.5 | to_number %}Convert a query parameter to boolean
{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}Sets the show_buttons variable to true unless the show_btns query parameter is present and set to false.
Convert a query parameter to integer
{% var limit = request.query_params['limit'] | to_int | default: 20 %}Sets the limit variable to 20 unless the limit query parameter is present and set to a valid integer.
Convert a query parameter to number
{% var average = request.query_params['average'] | to_number | default: 2.5 %}Sets the average variable to 2.5 unless the average query parameter is present and set to a valid number.
Converts a date to the specified timezone.
{% var sep9 = '2009-09-09 14:00:00Z' | date | to_timezone: 'America/New_York' %}Format a date as a short date string
{{sep9 | format: "d"}}9/9/2009
Formats a date as a short date string (d = short date).
Format a date as a short date string with the time
{{sep9 | format: "g"}}9/9/2009 10:00 AM
Formats a date as a short date string with the time (g = short date with time).
Format a date as a long date string
{{sep9 | format: "D"}}Sunday, September 9, 2009
Formats a date as a long date string (D = long date).
Format a date as a long date string with the time
{{sep9 | format: "f"}}Sunday, September 9, 2009 10:00 AM
Formats a date as a long date string with the time (f = long date with time).
Format a date according to the ISO 8601 standard
{{sep9 | format: "o"}}9/9/2009 2:00:00 PM
Formats a date according to the ISO 8601 standard (o = round trip format with offset).
Format a date as a sortable date string
{{sep9 | format: "u"}}9/9/2009 2:00:00 PM
Formats a date as a sortable date string (u = universal sortable date in UTC timezone).
Format a date to a long date string using a custom date format string
{{sep9 | format: "MMMM dd, yyyy 'at' HH:mm:ss"}}September 09, 2009 at 10:00:00
Formats a date using a custom .NET date format string.
Format a date to a short date string using a custom date format string
{{sep9 | format: "hh:mm tt 'on' MM-dd-yy"}}10:00 AM on 09-09-09
Formats a date using a custom .NET date format string.
You can also use the date filter to format a date
{{sep9 | date: "hh:mm tt 'on' MM-dd-yy"}}10:00 AM on 09-09-09
The date and format filters use the same format strings for dates, but the date filter can only be used to format dates while the format filter can also be used to format numbers and time diffs.
Display the article post date in multiple timezones
{{ article.post_date | to_timezone: session.user_timezone }} local time
{{- article.post_date | to_timezone: 'UTC' }} UTC
{{- article.post_date | to_timezone: 'Europe/Rome' }} CET2026-02-16 6:00:00 local time 2026-02-16 10:00:00 UTC 2026-02-16 11:00:00 CET
Convert a date to a different timezone and display it with formatting
{%- if entity.alt_timezone.is_valid -%}
{{- entity.alt_date | to_timezone: entity.alt_timezone | date: 'f' }} {{ entity.alt_timezone -}}
{%- endif -%}2026-02-16 12:00:00