String Filters

String Filters

append filter

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

Examples

Append text onto the end of a string

Append text

Copy
{{"fire" | append:"truck"}}

capitalize filter

Capitalize words in a string

capitalize

Examples

Capitalize all of the words in a sentance

Capitalize words in a string

Copy
{{"a freight train running through the" | capitalize}}

classname filter

Removes 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

Examples

Three ways to use the classname filter to convert text into a valid CSS classname

Convert text to a classname

Copy
{{"a long classname!" | classname}}
{{"a long classname!" | classname: "_"}}
{{"a long classname!" | classname: ""}}

downcase filter

Convert a string to lowercase

downcase

Examples

Convert all characters in a string to lowercase.

Convert a string to lowercase

Copy
{{"A Freight TRAIN Running TRHOUGH THE" | downcase}}

escape filter

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

Examples

Escape HTML characters in a string for output inside other HTML markup.

Escape HTML characters in a string

Copy
<p title="{{"<p>A string with HTML & other characters</p>" | escape}}">...

escape_once filter

Encode a string to be output as HTML, without changing existing escaped entities.

escape_once

Examples

Escape HTML characters in a string for output inside other HTML markup. If HTML characters have already been escaped, do not "double-escape" them.

Escape HTML characters in a string once

Copy
<p title="{{"&lt;p&gt;A string with some characters encoded & others not encoded&lt;/p&gt;" | escape_once}}">...

DEPRECATED for_json filter

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

Examples

Use the for_json filter on variables that both do and do not have values

For Json Deprecation

Copy
{"something": {{'with "value"' | for_json}} }
{"something": {{null | for_json}} }

h filter (alias for escape)

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

html_decode filter

Decodes any encoded HTML entities (eg: &lt; becomes <)

html_decode

Examples

Decode any encoded HTML entities inside a string.

Decode HTML entities in a string

Copy
{{"&lt;p&gt;A string with HTML &amp; other characters&lt;/p&gt;" | html_decode}}

html_encode filter

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

Examples

Encode a string for output inside other HTML markup.

Encode HTML entities in a string

Copy
<p title="{{"<p>A string with HTML & other characters</p>" | html_encode}}">...

index filter

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

Examples

Multiple ways to use the index filter to search for text inside a string.

Get Substring Indexes with Various Arguments

Copy
{% var input = 'ABC About' %}
{{input | index: 'A'}}
{{input | index: 'A', 1}}
{{input | index: 'Ab'}}
{{input | index: 'Ab', 0, true}}
{{input | index: 'D'}}

json_decode filter

Decode a json encoded string

json_decode

Examples

Use the json_decode filter to decode a json encoded string

Decode a json encoded string

Copy
{{'\"liquid\" filter' | json_decode}}

json_encode filter

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.

Examples

Use the json_encode filter to format the input for output as json properties. While most usefulf or strings, this can also be used with other object types.

Json_encode various object types

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

last_index filter

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

Examples

Multiple ways to use the last_index filter to search for text inside a string.

Getting the last substring indexes with various arguments

Copy
{% var input = 'ABC About' %}
{{input | last_index: 'A'}}
{{input | last_index: 'A', 3}}
{{input | last_index: 'AB'}}
{{input | last_index: 'AB', -1, true}}
{{input | last_index: 'a'}}

lstrip filter

Removes whitespace from the beginning of a string

lstrip

Examples

3 filters to remove whitespace from before and after strings

Various ways to strip whitespace from strings

Copy
{% var sentence_with_extra_whitespace = ' The quick brown fox jumps over the lazy dog. ' %}
[{{sentence_with_extra_whitespace | lstrip}}]
[{{sentence_with_extra_whitespace | rstrip}}]
[{{sentence_with_extra_whitespace | strip}}]

newline_to_br filter

Add <br /> tags in front of all newlines in the current string

newline_to_br

Examples

Add <br /> in front of all newlines in a string

Copy
{% capture input -%}
ABC
DEF
GHI
{%- endcapture -%}
{{input | newline_to_br}}

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.

Examples

Add some numbers together

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

prepend filter

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

Examples

Prepend text onto the beginning of a string

Prepend text

Copy
{{"truck" | prepend:"fire"}}

remove filter

Remove all occurrences of search from the current string.

remove: String search

Examples

Use the remove and remove_first filters to remove a string from another string

Remove text from the input string

Copy
{% var input = 'apply for apples app development' %}
{{input | remove:'app'}}
{{input | remove_first:'app'}}
{{input | remove_first:'app', 2}}

The remove and remove_first filters are case-sensitive

{{ input | remove:'App' }}

remove_first filter

Remove the first occurrence(s) of search from the current string.

remove_first: String searchInteger num_replacements

Examples

Use the remove and remove_first filters to remove a string from another string

Remove text from the input string

Copy
{% var input = 'apply for apples app development' %}
{{input | remove:'app'}}
{{input | remove_first:'app'}}
{{input | remove_first:'app', 2}}

The remove and remove_first filters are case-sensitive

{{ input | remove:'App' }}

replace filter

Replace all occurrences of search inside the current string with replacement

replace: String searchString replacement

Examples

Use the replace and replace_first filters to replace a string with another string inside the input

Replace text in the input string

Copy
{% var input = 'apply for apples app development' %}
{{input | replace:'app', 'mop'}}
{{input | replace_first:'app', 'mop'}}
{{input | replace_first:'app', 'mop', 2}}

The replace and replace_first filters are case-sensitive

{{ input | replace:'App', 'Mop'}}

replace_first filter

Replace the first occurrence(s) of search inside the current string with replacement

replace_first: String searchString replacementInteger num_replacements

Examples

Use the replace and replace_first filters to replace a string with another string inside the input

Replace text in the input string

Copy
{% var input = 'apply for apples app development' %}
{{input | replace:'app', 'mop'}}
{{input | replace_first:'app', 'mop'}}
{{input | replace_first:'app', 'mop', 2}}

The replace and replace_first filters are case-sensitive

{{ input | replace:'App', 'Mop'}}

replace_regex filter

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

Examples

Use the replace_regex and replace_regex_first filters to use advanced matching logic to replace a string with another string inside the input

Replace text in the input string using a regex

Copy
{% var input = 'The quick brown dog jumps over the lazy dog.' %}
{{input | replace_regex:'/dog/i', 'dragon'}}
{{input | replace_regex_first:'/dog/i', 'dragon'}}
{{input | replace_regex_first:'(quick|brown|lazy)', 'adjective:$1', 2}}

replace_regex_first filter

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

Examples

Use the replace_regex and replace_regex_first filters to use advanced matching logic to replace a string with another string inside the input

Replace text in the input string using a regex

Copy
{% var input = 'The quick brown dog jumps over the lazy dog.' %}
{{input | replace_regex:'/dog/i', 'dragon'}}
{{input | replace_regex_first:'/dog/i', 'dragon'}}
{{input | replace_regex_first:'(quick|brown|lazy)', 'adjective:$1', 2}}

reverse filter

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.

Examples

Use the reverse filter to reverse either a string or a list

Using the reverse filter

Copy

When used on null input

{{null | reverse | object_type}}

When used on a string

{{"string" | reverse}}

When used on a list

{{"item1,item2,item3" | split:"," | reverse | join:" "}}

rstrip filter

Removes whitespace from the end of a string

rstrip

Examples

3 filters to remove whitespace from before and after strings

Various ways to strip whitespace from strings

Copy
{% var sentence_with_extra_whitespace = ' The quick brown fox jumps over the lazy dog. ' %}
[{{sentence_with_extra_whitespace | lstrip}}]
[{{sentence_with_extra_whitespace | rstrip}}]
[{{sentence_with_extra_whitespace | strip}}]

size filter

Returns the length of the input string or list.

size

If the input is not a string or list returns 0.

Examples

Use the size filter to get the size of a string or a list

Using the size filter

Copy

When used on null input

{{null | size}}

When used on a string

{{"string" | size}}

When used on a list

{{"item1,item2,item3" | split:"," | size}}

When used on anything else

{{request.date | size}}

slice filter

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.

Examples

Use the slice filter to get a portion of a string or list.

Using the slice filter

Copy

When used on null input

{{null | slice | object_type}}

When used on a string

{{"string" | slice: 2}}
{{"string" | slice: 2, 3}}

When used on a list

{{"ab,cd,ef,gh,ij,kl,mn,op,qr,st,uv,wx,yz" | split:"," | slice: 2, 3 | join: " "}}

With a negative start value

{{"string" | slice: -2}}

With a negative length

{{"string" | slice: 2, -1}}

With a negative start and length

{{"string" | slice: -4, -2}}

With length = 0

{{"string" | slice: -4, 0}}

With a really large negative start

{{"string" | slice: -20}}

With start higher than the input length

[{{"string" | slice: 20}}]

With a calculated length less or equal to 0

[{{"string" | slice: 2, -4}}]

Does not do anything if the object is not a string or a list

{{ request.date | slice: 2 }}

split filter

Split a string into a list of substrings separated by the given separator

split: String separator

Examples

Use the split filter to convert a string into a list of strings separated by the given separator

Using the split filter

Copy
{{'The quick brown fox jumps over the lazy dog.' | split:" " | json_encode}}

Split on multiple characters

{{'She sells sea shells on the sea shore.' | split:"sea" | json_encode}}

Does not include empty strings in the result

{{"110100101" | split:'1' | json_encode}}

Use an empty pattern to split the string into individual characters

{{"abcdef" | split:'' | json_encode}}

strip filter

Removes whitespace from the beginning and end of a string

strip

Examples

3 filters to remove whitespace from before and after strings

Various ways to strip whitespace from strings

Copy
{% var sentence_with_extra_whitespace = ' The quick brown fox jumps over the lazy dog. ' %}
[{{sentence_with_extra_whitespace | lstrip}}]
[{{sentence_with_extra_whitespace | rstrip}}]
[{{sentence_with_extra_whitespace | strip}}]

strip_html filter

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.

Examples

Strip HTML from an input string

Copy
{{'<p>The quick brown fox jumps over the lazy dog.</p>' | strip_html}}
{% capture input -%}
<script>... this will strip script blocks ...</script>
<style>... this will also strip style blocks ...</style>
<!-- and this will strip HTML comments -->
<p title="this will strip the open and close tags but leave the content intact">The quick brown fox jumps over the lazy dog.</p>
<br />
<img src="..." alt="note that this will also strip images" />
{%- endcapture -%}
{{input | strip_html | strip}}

Could result in unexpected behavior with poorly formatted input

{% capture input -%}
//script outside of a script tag
if (a < b)
doSomething();
if(a > b)
doSomethingElse();
//endscript
{%- endcapture -%}
{{input | strip_html | strip}}

Could result in unexpected behavior with poorly formatted input

{% capture input -%}
<p>The following invalid markup contains an unescaped &gt; character in an HTML attribute:
<input type="button" onclick="if(a>b) doSomething();" value="Do Something" /></p>
{%- endcapture -%}
{{input | strip_html | strip}}

strip_newlines filter

Removes all newlines from a string

strip_newlines

Examples

Use the strip_newlines filter to remove all newlines from a string

Remove newlines from a string

Copy
{% capture input -%}
ABC
DEF
GHI
{%- endcapture -%}
{{input | strip_newlines}}

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.

Examples

Use the times filter to multiply a number by another number

Multiply numbers

Copy
{{4 | times:2}}
{{4.1 | times:-2.2}}

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

Using the times filter with a string

Copy

Current functionality

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

Future functionality

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

Potential Replacement

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

Alternate Replacement

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

truncate filter

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

Examples

Use the truncate, truncate_to_word, or truncate_words filter to shorten text to a specific number of characters or words.

Truncating text

Copy
{% var input = 'The quick brown fox jumps over the lazy dog.' %}

truncate

{{input | truncate:33}}
{{input | truncate:33 | size}}
{{input | truncate:31, " (more)"}}
{{input | truncate:33, ""}}
{{'Shorter than 33 characters' | truncate: 33}}

truncate_to_word

{{input | truncate_to_word:30}}
{{input | truncate_to_word:30 | size}}
{{input | truncate_to_word:30, false}}
{{input | truncate_to_word:30, false | size}}

truncate_words

{{input | truncate_words:3}}
{{input | truncate_words:3, " (more)"}}
{{input | truncate_words:9}}

truncate_to_word filter

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.

Examples

Use the truncate, truncate_to_word, or truncate_words filter to shorten text to a specific number of characters or words.

Truncating text

Copy
{% var input = 'The quick brown fox jumps over the lazy dog.' %}

truncate

{{input | truncate:33}}
{{input | truncate:33 | size}}
{{input | truncate:31, " (more)"}}
{{input | truncate:33, ""}}
{{'Shorter than 33 characters' | truncate: 33}}

truncate_to_word

{{input | truncate_to_word:30}}
{{input | truncate_to_word:30 | size}}
{{input | truncate_to_word:30, false}}
{{input | truncate_to_word:30, false | size}}

truncate_words

{{input | truncate_words:3}}
{{input | truncate_words:3, " (more)"}}
{{input | truncate_words:9}}

truncate_words filter

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.

Examples

Use the truncate, truncate_to_word, or truncate_words filter to shorten text to a specific number of characters or words.

Truncating text

Copy
{% var input = 'The quick brown fox jumps over the lazy dog.' %}

truncate

{{input | truncate:33}}
{{input | truncate:33 | size}}
{{input | truncate:31, " (more)"}}
{{input | truncate:33, ""}}
{{'Shorter than 33 characters' | truncate: 33}}

truncate_to_word

{{input | truncate_to_word:30}}
{{input | truncate_to_word:30 | size}}
{{input | truncate_to_word:30, false}}
{{input | truncate_to_word:30, false | size}}

truncate_words

{{input | truncate_words:3}}
{{input | truncate_words:3, " (more)"}}
{{input | truncate_words:9}}

upcase filter

Convert a string to uppercase

upcase

Examples

Convert all characters in a string to uppercase.

Convert a string to uppercase

Copy
{{"A Freight TRAIN Running TRHOUGH THE" | upcase}}

url_decode filter

Decode a url encoded string.

url_decode: Boolean formdata

Examples

Use the url_encode and url_decode filters to encode strings for use in URLs, and to decode strings that have been url encoded.

Url Encoding and Decoding

Copy

url_encode

{{"liquid filter" | url_encode}}
{{"liquid filter" | url_encode:true}}

url_decode

{{"liquid%20filter" | url_decode}}
{{"liquid+filter" | url_decode}}
{{"liquid+filter" | url_decode:true}}

url_encode filter

Encode a string to be used in a URL.

url_encode: Boolean formdata

Examples

Use the url_encode and url_decode filters to encode strings for use in URLs, and to decode strings that have been url encoded.

Url Encoding and Decoding

Copy

url_encode

{{"liquid filter" | url_encode}}
{{"liquid filter" | url_encode:true}}

url_decode

{{"liquid%20filter" | url_decode}}
{{"liquid+filter" | url_decode}}
{{"liquid+filter" | url_decode:true}}