Number Filters

abs filter

Returns the absolute value of a number.

abs

Will attempt to convert the input to a number before calculating the absolute value, and will return 0 if it is unable to convert the input to a number.

Example Calculate the absolute value of a numberGet the absolute value of a number with the abs filter (removes negative sign).

{{-2 | abs}}

-2

{{"-2" | abs}}

-2

{{3.159 | abs}}

3.159

{{null | abs}}

{{"not a number" | abs}}

at_least filter

Limits the input to a minimum value.

at_least: number minimum

Converts both the input and the minimum values to numbers if they are not already numbers. If the input and minimum values cannot both be converted to numbers, return the unaltered input instead.

Example Use at_least and at_most to clamp numbers to a rangeUse the at_least and at_most filters to limit a number to minimum and maximum values.

at_least

{{-1 | at_least:5}}

{{5.255 | at_least:-1.112}}

5.255

at_most

{{-1 | at_most:5}}

-1

{{5.255 | at_most:-1.112}}

-1.112

with non-number inputs and parameters

{{"-1" | at_least:"5" | json_encode}}

{{"5" | at_most:"-1.345" | json_encode}}

-1.345

{{null | at_least:"5" | object_type}}

null

{{"string" | at_most:5}}

string

{{"5" | at_least:"string" | json_encode}}

"5"

at_most filter

Limits the input to a maximum value.

at_most: number maximum

Converts both the input and the maximum values to numbers if they are not already numbers. If the input and maximum values cannot both be converted to numbers, return the unaltered input instead.

Example Use at_least and at_most to clamp numbers to a rangeUse the at_least and at_most filters to limit a number to minimum and maximum values.

at_least

{{-1 | at_least:5}}

{{5.255 | at_least:-1.112}}

5.255

at_most

{{-1 | at_most:5}}

-1

{{5.255 | at_most:-1.112}}

-1.112

with non-number inputs and parameters

{{"-1" | at_least:"5" | json_encode}}

{{"5" | at_most:"-1.345" | json_encode}}

-1.345

{{null | at_least:"5" | object_type}}

null

{{"string" | at_most:5}}

string

{{"5" | at_least:"string" | json_encode}}

"5"

ceil filter

Returns the next integer value greater than or equal to the input.

ceil

Attempts to converts the input to a number if it is not already a number. Returns null if it is unable to convert the input to a number.

Example Using filters to round numbers up and downUse the ceil, floor, and round filters to round numbers up and down.

ceil

{{3.2 | ceil}}

{{"-3.159" | ceil}}

-3

floor

{{5.9 | floor}}

{{"-3.159" | floor}}

-4

round

{{9.82 | round}}

{{-9.825 | round: 2}}

-9.82

{{-9.835 | round: 2}}

-9.84

Non-numeric input

{{null | ceil | object_type}}

null

{{"string" | round | object_type}}

null

currency filter

Converts the input into a formatted currency as specified by language_tag.

currency: string language_tag

Attempts to convert the input to a number, and if it cannot be converted to a number, the currency filter will return the input as a string instead. If the input is null, returns null. Passing an invalid language_tag results in undefined behavior - likely resulting in a liquid error.

Example Format a number as currencyUse the currency filter to format a tag as currency, including the leading or trailing currency identifier.

en-US (default)

{{12345.6789 | currency}}

$12,345.68

{{12345 | currency: 'en-US'}}

$12,345.00

de

{{input | currency: 'de-DE'}}

12.345,68 €

en-GB

{{input | currency: 'en-GB'}}

£12,345.68

es-VE

{{input | currency: 'es-VE'}}

Bs.S12.345,68

zh-CN

{{input | currency: 'zh-CN'}}

￥12,345.68

divided_by filter

Divide the input by operand.

divided_by: number operand

Example Using the divided_by filterUse the divided_by filter to divide one number by another.

{{8 | divided_by:2}}

{{13.3 | divided_by:1.4}}

9.5

floor filter

Returns the next integer value less than or equal to the input value.

floor

Attempts to converts the input to a number if it is not already a number. Returns null if it is unable to convert the input to a number.

Example Using filters to round numbers up and downUse the ceil, floor, and round filters to round numbers up and down.

ceil

{{3.2 | ceil}}

{{"-3.159" | ceil}}

-3

floor

{{5.9 | floor}}

{{"-3.159" | floor}}

-4

round

{{9.82 | round}}

{{-9.825 | round: 2}}

-9.82

{{-9.835 | round: 2}}

-9.84

Non-numeric input

{{null | ceil | object_type}}

null

{{"string" | round | object_type}}

null

format_number filter

Returns the input formatted as a string using the provided format string. The format string must be a valid standard or custom .NET numeric format string.

format_number: string format

Returns null if the input cannot be converted to a number.

Example Format dates and numbers (overview)This is a brief example of formatting dates and numbers. There are additional detailed examples of format strings for dates, 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).

Example How to use the format filter to format numbersFormat numbers using standard or custom .NET numeric format strings.

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

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.

minus filter

Subtracts the operand from the input.

minus: number operand

Example Using the minus filterUse the minus filter to subtract one number from another.

{{5 | minus:1}}

{{13.3 | minus:14.4}}

-1.1

modulo filter

Return the remainder of the input when divided by the operand.

modulo: number operand

If the input is negative, the result will also be negative. Otherwise the result will be positive.

Example Using the modulo filterUse the modulo filter to get the remainder when one number is divided by another.

{{5 | modulo:3}}

{{13.3 | modulo:1.4}}

0.7

{{-3 | modulo:2}}

-1

{{3 | modulo:-2}}

plus filter

Adds the operand to the current value. Note that this filter behaves differently if the current value is a string

plus: number operand

The plus filter may behave differently when used with string input. When used with a string input it may append text to the current value, although that behavior is deprecated and should be replaced by the append filter for optimal forward-compatibility.

Example Add some numbers togetherAdd numbers with the plus filter or assign/set after converting with to_number if needed.

3+5 = {{3 | plus: 5-}}
-4.2+2.1 = {{-4.2 | plus: 2.1}}

3+5 = 8
-4.2+2.1 = -2.1

Add two integers with plus

3+5 = {{3 | plus: 5}}

3+5 = 8

Uses the plus filter to add two integer values.

Add decimal numbers with plus

-4.2+2.1 = {{-4.2 | plus: 2.1}}

-4.2+2.1 = -2.1

Shows that the plus filter also works with decimal numbers.

round filter

Rounds the input to the specified number of decimal places.

round: integer places

Attempts to converts the input to a number if it is not already a number. Returns null if it is unable to convert the input to a number, or if places is specified but cannot be converted to an integer. If the input is exactly halfway between the smaller and larger number, the round filter will attempt to round toward the nearest even number in the last decimal place (eg: 4.35 rounded to one decimal place would be 4.4)

Example Using filters to round numbers up and downUse the ceil, floor, and round filters to round numbers up and down.

ceil

{{3.2 | ceil}}

{{"-3.159" | ceil}}

-3

floor

{{5.9 | floor}}

{{"-3.159" | floor}}

-4

round

{{9.82 | round}}

{{-9.825 | round: 2}}

-9.82

{{-9.835 | round: 2}}

-9.84

Non-numeric input

{{null | ceil | object_type}}

null

{{"string" | round | object_type}}

null

times filter

Multiply the input by the operand.

times: number operand

This filter currently behaves differently if the input is a string and the operand is an integer. In that case the result is a list of strings with input repeated operand times.

Example Using the times filter with a stringYou can currently use the times to multiply a string into a list of identical strings, although this behavior is deprecated. If you need this functionality you are advised to find a different way to accomplish it.

Current functionality

{{"string" | times:2 | json_encode}}

["string","string"]

Future functionality

{{"string" | times:2 | json_encode}}

Liquid error

Potential Replacement

{%- map string for i in (1..2) %}string{% endmap -%}
{{-string | json_encode}}

["string","string"]

Alternate Replacement

{%- capture string %}{% for i in (1..2) %}string{% unless forloop.last %},{% endunless %}{% endfor %}{% endcapture -%}
{{-string | split:',' | json_encode}}

["string","string"]

Example Multiply numbersUse the times filter to multiply a number by another number

{{4 | times:2}}

{{4.1 | times:-2.2}}

-9.02

to_int filter

Converts the input to an integer.

to_int

If the input is null, returns 0. If the input is non-null and cannot be convert to an integer, returns null.

Example Convert to integerConvert a query parameter to an integer value with a default value.

{% var limit = request.query_params['limit'] | default: 20 | to_int %}

Example Default Numeric Query ParameterProvide a default value for a numeric query parameter

{% var page = request.query_params['page'] | to_int | default: 1 %}

Example Convert query parameters to booleans and numbersShows how to convert query string parameters into strongly-typed values using to_boolean, to_int, and 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.

Each sub-example demonstrates a common pattern for converting query parameter values while providing sensible defaults.

to_number filter

Converts the input to a number.

to_number

If the input is null, returns 0. If the input is non-null and cannot be convert to an integer, returns null.

Example Convert to numberConvert a query parameter to a number with a default value.

{% var average = request.query_params['average'] | default: 2.5 | to_number %}

Example Convert query parameters to booleans and numbersShows how to convert query string parameters into strongly-typed values using to_boolean, to_int, and 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.

Each sub-example demonstrates a common pattern for converting query parameter values while providing sensible defaults.