Filters may be used to modify the output of objects before either being stored in a variable or output to the page. Filters should be used as "expression | filter_name:filterParam1, filterParam2, etc..." (eg: {{ request.date | inspect: 2, true }}, or {% assign end_date = request.date | add_weeks:1 %}).
Multiple filters may be applied to an object at the same time and are processed in the same order that they appear in the markup. Eg: {% assign my_date = request.date | midnight | add_hours:3 %} will result in a different date than {% assign my_date = request.date | add_hours:3 | midnight %}
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.
default: object default
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.
format: String format
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: Number depthBoolean force_load
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.
object_type: Boolean generic_object_check
The most common object_type values are: null, object, string, boolean, date, number, list, other specific object types (article, blog_post, etc...)
object
{% set_content_type %}
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).
rand: Integer lengthBoolean allow_repeatsBoolean prevent_cache
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.
Converts the input to true or false if possible. If not returns null.
to_boolean
boolean
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.
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.
for_json
{% for %}
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.
number
Converts a date to the specified timezone.
to_timezone: String timezone
{{ timezone }}
{% set_timezone %}
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.
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.
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.
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.
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.
Divide the input by operand.
divided_by: Number operand
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.
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.
number
Subtracts the operand from the input.
minus: Number operand
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.
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.
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)
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.
{{ time }}
Go to to_int filter filter documentation
Go to to_number filter filter documentation
Add text to the end of the input. If the input is not already a string it will be converted to one using the default behavior for its object type.
append: String text
Append text onto the end of a string
Append text
CopyCapitalize words in a string
capitalize
Capitalize all of the words in a sentance
Capitalize words in a string
CopyRemoves all non-alphanumeric characters other than dashes and underscores from a string and replaces them with the separator (or nothing if the separator is empty) to form a valid CSS classname.
classname: String separator
Convert a string to lowercase
downcase
Encode a string to be output as HTML. All special HTML characters will be converted to their equivalent HTML character entities (eg: < becomes &lt;)
escape
Encode a string to be output as HTML, without changing existing escaped entities.
escape_once
Go to DEPRECATED for_json filter filter documentation
Alias for escape, which encodes a string to be output as HTML. Although "h" is shorter, "escape" is preferred due to its improved readability and maintainability.
h
Decodes any encoded HTML entities (eg: &lt; becomes <)
html_decode
{{ html }}
Encode a string to be output as HTML. All special HTML characters will be converted to their equivalent HTML character entities (eg: < becomes <). This is functionally identical to the "escape" filter, though it may be more intuitive in some contexts - such as when using both the html_encode and html_decode filters to execute more advanced string manipulation.
html_encode
{{ html }}
Returns the 0-based location of the find string in the current string, or -1 if it cannot be found. If start is greater than 0, the search will begin at the specified index. To ignore capitalization, set ignorecase to true.
index: String findInteger startBoolean ignorecase
Decode a json encoded string
json_decode
Encode the input object to be used as a JSON property.
json_encode
Null values output the string "null". Dates are output using the ISO 8601 standard. Booleans are output as "true" or "false". Numbers are output as numbers. Strings are output as json encoded strings with quote marks properly escaped.
Returns the last 0-based location of the last occurrence of find string in the current string, or -1 if it cannot be found. If start is greater than or equal to 0, the search will begin at the specified index. To ignore capitalization, set ignorecase to true.
last_index: String findInteger startBoolean ignorecase
Removes whitespace from the beginning of a string
lstrip
Add <br /> tags in front of all newlines in the current string
newline_to_br
Go to plus filter filter documentation
Add text to the beginning of the input. If the input is not already a string it will be converted to one using the default behavior for its object type.
prepend: String text
Remove all occurrences of search from the current string.
remove: String search
Remove the first occurrence(s) of search from the current string.
remove_first: String searchInteger num_replacements
Replace all occurrences of search inside the current string with replacement
replace: String searchString replacement
Replace the first occurrence(s) of search inside the current string with replacement
replace_first: String searchString replacementInteger num_replacements
Replace all occurrences of pattern inside the current string with replacement using a regular expression - making it possible to search for more complicated expressions and replace using the resulting captured groups.
replace_regex: String patternString replacement
Replace the first occurrence(s) of pattern inside the current string with replacement using a regular expression - making it possible to search for more complicated expressions and replace using the resulting captured groups.
replace_regex_first: String patternString replacementInteger num_replacements
Reverses the input string or list.
reverse
When used with a string as input, the result is a string. Otherwise the result is a list.
Removes whitespace from the end of a string
rstrip
Returns the length of the input string or list.
size
If the input is not a string or list returns 0.
Return a part of the current string or list.
slice: Integer startInteger length
If the input is a string this will return a string. If it is a list it will return a list. Otherwise it will not do anything and will return the unaltered input.
Split a string into a list of substrings separated by the given separator
split: String separator
Removes whitespace from the beginning and end of a string
strip
Removes all HTML tags from a string
strip_html
This filter uses simple pattern matching to remove HTML tags. If the input is poorly formatted or contains unusual character sequences - particularly involving the '<' and '>' characters - this could result in unexpected behavior.
{{ html }}
Removes all newlines from a string
strip_newlines
Go to times filter filter documentation
Truncates a string down to length characters. If the original string is longer than length characters, the result will end with truncate_string.
truncate: Integer lengthString truncate_string
Truncates a string down to length characters. If the string would be broken in the middle of a word, ensures that the break happens either before or after the word. If the string is truncated it will end with truncate_string.
truncate_to_word: Integer lengthBoolean break_before_wordString truncate_string
The truncate_to_word uses a naive algorithm for word counting that considers words as one or more letters, digits, underscores, or apostrophes. All other characters are considered non-word characters in between words. This means that a string could still be truncated in the middle of a hypenated word or a word with other non-word characters such as "awe-inspiring", "r&r", "1.25", "3/4", etc.... This filter also does not strip or consolidate whitespace, or handle HTML markup any different than normal text.
Truncates the input string down to length words. If the input is longer than length words, appends truncate_string to the end of the truncated string.
truncate_words: Integer lengthString truncate_string
The truncate_words uses a naive algorithm for word counting that considers words as one or more letters, digits, underscores, or apostrophes. All other characters are considered non-word characters in between words. This means that hyphenated words such as "awe-inspiring" are counted as two words, as are "words" with other characters between letters, such as "r&r", "1.25", "3/4", etc.... This filter also does not strip or consolidate whitespace, or handle HTML markup any different than normal text.
Convert a string to uppercase
upcase
Decode a url encoded string.
url_decode: Boolean formdata
{% image_url %}
{{ url }}
{% set_canonical_url %}
Encode a string to be used in a URL.
url_encode: Boolean formdata
{% image_url %}
{{ url }}
{% set_canonical_url %}
Return a date object operand years in the future from the input date.
add_years: Integer operand
If operand is negative, return a date that many years in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand weeks in the future from the input date.
add_weeks: Integer operand
If operand is negative, return a date that many weeks in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand seconds in the future from the input date.
add_seconds: Integer operand
If operand is negative, return a date that many seconds in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand months in the future from the input date.
add_months: Integer operand
If operand is negative, return a date that many months in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand minutes in the future from the input date.
add_minutes: Integer operand
If operand is negative, return a date that many minutes in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand hours in the future from the input date.
add_hours: Integer operand
If operand is negative, return a date that many hours in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Return a date object operand days in the future from the input date.
add_days: Integer operand
If operand is negative, return a date that many days in the past from the input date.
{% add_stylesheet %}
{% add_javascript %}
{% add_javascript inline %}
{% add_stylesheet inline %}
Returns the input as a date. If format is specified, converts the date to a string before returning it using the given format. The format must be a valid standard or custom .NET date format.
date: String format
If the input is already a date object, it will be used as-is - either to be formatted or returned without alteration. If the input is a number, it will be interpreted as a unix timestamp - that is the seconds since the Unix Epoch (midnight on January 1, 1970 UTC). If the input is not already a date and is not a number, it will attempt to parse it as the string representation of a date. If the input cannot be converted to a date using any of the previous methods, it will use the current date and time - which will prevent the page from being fast-cached. In all cases where the date filter creates a new date object, it uses the current timezone - which defaults to the site's timezone but may be set explicitly using the {% set_timezone %} method.
Set a date range (e.g. from now to one month ahead) and fetch calendar_entries into the template.
Fetch calendar_entries for the next month using assign and date filters
Copy{{ date }}
{{ date_field }}
Return the input as a date at midnight of the same day. That is, with hours, minutes, and seconds set to 0.
midnight
If format is unspecified, returns a time_diff object describing the difference between the current date and the other date. If format is specified, converts the time difference to a string before returning it using the given format. If supplied, the format must be a valid standard or custom .NET TimeSpan format.
time_diff: time otherString format
{{ time_diff }}
{{ time }}
Returns the timezone that the date is in. If full is true or if an abbreviated timezone name is not available, returns the full timezone identifier (eg: "Europe/Rome"). If full is false (default) or not specified and an abbreviated timezone name is available returns the abbreviated timezone name (eg: "PST" or "PDT").
timezone: Boolean full
{{ timezone }}
Go to to_timezone filter filter documentation
Removes all null, empty, and invalid (is_valid == false, empty lists, etc..) objects from the list.
compact
Use the compact filter to remove null, empty, and invalid items from a list (e.g. for cleaner iteration or mapping).
How to use the compact filter
CopyRemove null and empty from a list
After map or other operations
When the list may contain invalid items
Adds all of the items from the other list onto the end of the input list.
concat: list other
If either the input or other is not a list, it will be treated as a list with a single object. If either is null, it will be treated as an empty list.
Returns the first item in the input list
first
If the input is not a list, it will be returned without modification.
Groups the list by the given property and returns the results as a list of objects. Each object in the result set has a Key property which is the value that they are grouped by and a Value property which is the list of objects that have the matching Key property. Any objects in the list that do not have the given property will be in a result with a null Key.
group_by: String property
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object.
{{ group_field }}
Returns the 0-based index of the first occurrence of find in the current list or string, or -1 if it cannot be found. If start is greater than 0, the search will begin at the specified index.
index: object findInteger startBoolean ignorecase
If the input is a string, will search for the index of find as a string in the input. If the input is a list, will search for the index of find in the list. If the input is neither a list or an object, the index filter will return 0 if find is the same as the input or -1 if it is not the same.
Go to index filter filter documentation
Returns a string with each element from the input list joined together with the glue string between elements.
join
If the input is not a list, it will be treated as a list with a single object. If either is null, it will be treated as an empty list. All objects in the list will be converted to a string using their default string output if they are not already strings.
Return a new list with the given property from every object in the input list.
map: String property
If the input is null, it will be treated as an empty list. If it is not null and not a list, it will be treated as a list with a single object.
{% map %}
Go to rand filter filter documentation
Go to size filter filter documentation
Remove all duplicate objects in the input list. If property is specified, objects are considered duplicate if their property value is the same.
uniq: String propertyBoolean ignorecase
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object.
Returns the last item in the input list
last
If the input is not a list, it will be returned without modification.
Go to last_index filter filter documentation
Returns the 0-based index of the last occurrence of find object in the current list or string, or -1 if it cannot be found. If start is greater than -1, the search will begin at the specified index.
last_index: object findInteger startBoolean ignorecase
If the input is a string, will search for the last index of find as a string in the input. If the input is a list, will search for the last index of find in the list. If the input is neither a list or an object, the index filter will return 0 if find is the same as the input or -1 if it is not the same.
Go to reverse filter filter documentation
Sorts the input list randomly. Unless prevent_cache is false, the shuffle filter will prevent the page from being fast-cached.
shuffle: Boolean prevent_cache
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object.
Go to slice filter filter documentation
Sort objects in the input list. If the property is specified, use it to sort objects in the list. Use the special string value "random" to sort the list in a random order - which is functionally identical to using the shuffle filter.
sort: String propertyBoolean ignorecase
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object.
Sort objects in the input list. If the property is specified, use it to sort objects in the list. Use the special string value "random" to sort the list in a random order - which is functionally identical to using the shuffle filter. The sort_natural filter ignores capitalization while the sort filter does not by default. For readability and consistency, it is advised to use the sort filter with the ignorecase property set to true instead of the sort_natural filter.
sort_natural: String property
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object.
Go to times filter filter documentation
Go to split filter filter documentation
Returns a new list which only contains items from the input list where the property has the specified value.
where: String propertyobject valueBoolean ignorecase
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object. If the property to filter by is null, the input list will be unfiltered.
Returns a new list which only contains items from the input list that match the given expression when the item is referenced as name.
where_exp: String nameString expression
If the input is null it will return an empty list. If the input is not null and is not a list, it will be treated as a list with a single object. If either name or expression are null or empty, the input list will be unfiltered.
Returns the unencrypted value of the input string using a shared secret and optional salt. If no salt is provided, a default salt value is used.
decrypt_aes: String secretString salt
Returns the encrypted value of the input string using a shared secret and optional salt. If no salt is provided, a default salt value is used.
encrypt_aes: String secretString salt
Encodes a string to a URL-safe base64 format. The difference between the base64 and URL-safe base64 formats is that the URL-safe format uses - and _ in place of + and /, which can cause problems when used in a URL.
base64_url_safe_encode
{% image_url %}
{{ url }}
{% set_canonical_url %}
Decodes a string from a URL-safe base64 format. The difference between the base64 and URL-safe base64 formats is that the URL-safe format uses - and _ in place of + and /, which can cause problems when used in a URL.
base64_url_safe_decode
{% image_url %}
{{ url }}
{% set_canonical_url %}
Encodes a string to Base64 format
base64_encode
Decodes a string from Base64 format
base64_decode