Django filter glossary
Learn how to use Django filters to adjust and manipulate the variables shown in your messaging.
Klaviyo’s email and SMS editors support most built-in Django filters, in addition to a small number of custom filters. For example, the title filter can be used to apply title case formatting to a piece of text pulled in from a customer profile or event data. In this glossary, you will find a compilation of different filters, what they do, and examples of how they should be formatted. Given aliases are either Klaviyo or Django-specific.
Filters
abs
int, float → int, float
Given a number, returns its absolute value.
Example:
{{ -1.2|abs }} => 1.2
append
str | str → str
Given a string, returns a string with the target string appended to the end.
Example:
{{ "hello"|append:" world" }} => "hello world"
at_least
int, float | int, float → int, float
Given a number, returns the maximum of the number and the target value.
Example:
{{ 1|at_least:5.0 }} => 5.0
at_most
int, float | int, float → int, float
Given a number, returns the minimum of the number and the target value.
Example:
{{ 1|at_most:-1.0 }} => -1.0
base64_decode
str → str
Decodes the input from Base-64 format.
base64_encode
str → str
Encodes the input in Base-64 format. A common use case is encoding an email address, so it can be passed within a UTM parameter.
base64_url_safe_decode
str → str
Decodes the input from Base-64 format with URL-safe characters.
base64_url_safe_encode
str → str
Encodes the input in Base-64 format with URL-safe characters. Any encoded + will be replaced with - and any / will be replaced with _.
capitalize
str → str
Given a string, returns it with the first character in uppercase.
Alias: capfirst
ceil
str, int, float → str
Given a number, rounds it up to the nearest integer.
For more complex use cases, consider round_up instead.
Example:
{{ 5.01|ceil }} => "6.0"
compact
list → list
Given a list, returns a list without any undefined (None) elements.
Example:
{{ [{"name":"a"},None,None,None,{"name":"b"}]|compact }} => [{"name":"a"},{"name":"b"}]
concat
str, list | str, list → str, list
Given a string or list, returns a string or list with the target value appended to the end.
Example:
{{ [1,2,3]|concat:[4,5,6] }} => [1,2,3,4,5,6]
{{ 'hello'|concat:'world' }} => 'helloworld'
{{ 'hello'|concat:[4,5,6] }} => 'hello[4, 5, 6]'
count
str, list → int
Runs the python len() function on the input. If a string is provided, returns the number of characters. If a list is provided, returns the number of items.
Example:
{{ "hello"|count }} => 5
{{ ["a", "b", "c"]|count }} => 3
datetime_from_string
str → datetime.datetime
Parses the provided ISO 8601 datetime string into a python datetime object. If the string is not parsable, it is returned as is.
Example:
{{ "2022-07-22"|datetime_from_string }}
{{ "2022-07-22T21:00:52"|datetime_from_string }}
default
Any | Any → Any
Supplies a default value to be used if the variable is empty.
Example:
{{ first_name|default:'friend' }}
dictfilter
List[dict] | str → List[dict]
Filters a dictionary to match the criteria of an argument. The argument is a string representing an infix operation in the following format:
<DICT_ITEM_KEY><OPERATOR><COMPARE_VALUE>
An operator can be one of <, <=, ==, !=, =>, >.
Example:
{{ [{'a': 2}, {'a': 3}]|dictfilter:"a>2" }} => [{'a': 3}]
divide
str, int, float | str, int, float → float
Divides a number by a given number. If the input is not divisible, the return value is 0.0.
Example:
{{ "10"|divide:"2" }} => 5.0
downcase
str → str
Given a string, returns it with all characters in lowercase.
Alias: lower
escape
str → str
Escapes a string's HTML. Specifically, it makes these replacements:
<is converted to<.>is converted to>.'(single quote) is converted to'."(double quote) is converted to".&is converted to&.
Learn more in the Django docs.
Example:
{{ html_string|escape }}
escape_once
str → str
Given a string, returns it with ampersands, quotes, and angle brackets encoded for use in HTML. It does not change characters that have already been escaped.
Example:
{{ "<p>Hello<p>"|escape_once }} => "<p>Hello</p>"
{{ "<p>Hello & World</p>"|escape_once }} => "<p>Hello & World</p>"
find_replace
str | str → str
Takes a string and a replacement clause (string) separated by a pipe. Returns a string with all the specified values replaced.
Alias: replace
floatadd
int, str, float | int, str, float → float, str
Adds a number to the variable's value. If any error occurs, the return value is an empty string "".
Example:
{{ 1|floatadd:1.1 }} => 2.1
{{ "2"|floatadd:"3" }} => 5.0
floatformat
str, int, float | int → float
Specifies the number of decimal places to display. A common use case is to show a price with two decimal places, regardless of how many decimal places are supplied.
Learn more in the Django docs.
Example:
{{ "5.0003"|floatformat:2 }} => "5.0"
{{ "5"|floatformat:2 }} => "5.0"
floatsub
int, str, float | int, str, float → float, str
Subtracts a number from the variable's value. If any error occurs, the return value is an empty string "".
Example:
{{ 1.1|floatsub:1 }} => 0.1
{{ "3"|floatsub:"2" }} => 1.0
floor
str, int, float → str
Given a number, rounds it down to the nearest integer.
For more complex use cases, consider round_down instead.
Example:
{{ 5.9|floor }} => "5.0"
format_date_string
datetime.datetime → str
Formats a date variable as a string following this format: Feb. 11, 2016, 4:46 p.m.
httpize
str → str
Prepends http:// to an address, if not already present. Does not prepend to an address already starting with http or https.
Example:
{{ "domain.com"|httpize }} => "http://domain.com"
{{ "http://domain.com"|httpize }} => "http://domain.com"
httpsize
str → str
Prepends https:// to an address, if not already present. Does not prepend to an address already starting with http or https.
Example:
{{ "domain.com"|httpsize }} => "https://domain.com"
{{ "https://domain.com"|httpsize }} => "https://domain.com"
join
List[str] | str → str
Joins a list with a string.
Example:
{{ ['a', 'b', 'c']|join:" & " }} => "a & b & c"
length
str, list → int
Runs the python len() function on the input. If a string is provided, returns the number of characters. If a list is provided, returns the number of items.
Learn more in the Django docs.
list_to_string
List[str] → str
Converts a list into a string, with proper list punctuation. If a string is given, returns it as is.
Example:
arr = ['apple', 'banana', 'orange']
{{ event.arr|list_to_string }} == apple, banana and orange
arr = arr[:2]
{{ event.arr|list_to_string }} == apple and banana
list_where
list | str → list
Given a list of objects, returns a list of objects where the property is equal to the target value.
For more complex use cases, consider dictfilter instead.
Example:
{{ [{"name":"a"},{"name":"B"}]|list_where:"name=a" }} => [{"name":"a"}]
lookup
object, list | str, int → Any
Given an object or a list, returns the attribute specified. In the case where a list is provided, returns the items at the specified index number.
If the input is neither an object nor a list, it is returned as is.
Example:
{{ person|lookup:"first_name" }}
{{ item_list|lookup:1 }}
lstrip
str → str
Given a string, returns it with any leading whitespace removed.
Example:
{{ " Hello world "|lstrip }} => "Hello world "
map
list | str → list
Given a list, returns a list of values from a specific property of the items in the list.
Example:
{{ [{"name":"a"},{"name":"B"}]|map:"name" }} => ["a","B"]
md5_hash
str → str
Converts the given value into an md5 hash. Returns an empty string on error.
minus
int, str, float | int, str, float → float, str
Subtracts a number by a given number. If any error occurs, the return value is an empty string "".
Alias: floatsub
missing_image
str → str
If a provided image is invalid, supplies a blank image, so that no error displays.
missing_product_image
str → str
If a provided product image url is blank, supplies a placeholder image.
modulo
int, str | int, str → float
Returns the remainder of x divided by y.
Alias: remainder
multiply
str, int, float | str, int, float → float
Multiplies a number by a given number. If the input is not a number, the return value is 0.0.
Example:
{{ "10"|multiply:"2" }} => 20.0
{{ "a"|multiply:"2" }} => 0.0
newline_to_br
str → str
Given a string, returns a string with HTML newline characters (e.g., \r\n) replaced with HTML line break characters (<br>).
Alias: linebreaksbr
Example:
{{ "hello\r\nworld"|newline_to_br }} => "hello<br>world"
percentize
str, int, float | int → str
Converts a number to a percentage, with the number of decimal places specified in the argument. If no argument is included, 0 decimals will be shown.
Example:
{{ ".25"|percentize }} => 25%
{{ ".25"|percentize:2 }} => 25.00%
plus
int, str, float | int, str, float → float, str
Adds a number to the variable's value. If any error occurs, the return value is an empty string "".
Alias: floatadd
prepend
str | str → str
Given a string, returns a string with the target string prepended to it.
Example:
{{ "hello"|prepend:"world " }} => "world hello"
remainder
int, str | int, str → float
Returns the remainder of x divided by y.
Example:
{{ 5|remainder:2 }} => 1.0
{{ 6|remainder:2 }} => 0.0
remove
str | str → str
Given a string, returns a string with all occurrences of the target substring removed.
Example:
{{ "hello world, hello"|remove:"hello" }} => " world, "
remove_first
str | str → str
Given a string, returns a string with first occurrence of the target substring removed.
Example:
{{ "hello world, hello"|remove_first:"hello" }} => " world, hello"
remove_last
str | str → str
Given a string, returns a string with last occurrence of the target substring removed.
Example:
{{ "hello world, hello"|remove_last:"hello" }} => "hello world, "
replace
str | str → str
Takes a string and a replacement clause (string) separated by a pipe. Returns a string with all the specified values replaced.
Alias: find_replace
Example:
{{ "Hi, there,"|find_replace:",|-" }} will return "Hi- there-"
replace_first
str | str → str
Takes a string and a replacement clause (string) separated by a pipe. Returns a string with only the first occurrence of the specified value replaced.
Example:
{{ "Hi, there,"|replace_first:",|-" }} will return "Hi- there,"
replace_last
str | str → str
Takes a string and a replacement clause (string) separated by a pipe. Returns a string with only the last occurrence of the specified value replaced.
Example:
{{ "Hi, there,"|replace_last:",|-" }} will return "Hi, there-"
resplit
str | str → List[str]
Splits a string based on the given regex pattern.
Example:
Split on whitespace characters:
{{ "apple banana\n orange"|resplit:'\s+' }} => ['apple', 'banana', 'orange']
reverse
list → list
Given a list, returns a list in reverse order.
Example:
{{ [3,1,2,2]|reverse }} => [2,2,1,3]
{{ [{"name":"a"},{"name":"B"}]|reverse }} => [{"name":"B"},{"name":"a"}]
round
str, int, float → str
Given a number, rounds it to the nearest integer.
Example:
{{ 5.01|round }} => "5.0"
{{ 5.05|round }} => "6.0"
round_down
str, int, float | Optional[str, int, float] → str
Rounds down the given number to the nearest integer. Optionally, a decimal place can be specified to change the rounding behavior.
Example:
{{ 5|round_down }} => "5.0"
{{ 5.99|round_down }} => "5.0"
{{ 5.99|round_down:2 }} => "5.98"
round_up
str, int, float | Optional[str, int, float] → str
Returns the ceiling of x, which is the largest integer greater than or equal to x.
Example:
{{ 5|round_up }} => "5.0"
{{ 5.01|round_up }} => "6.0"
{{ 5.123|round_up:2 }} => "5.13"
rstrip
str → str
Given a string, returns it with any trailing whitespace removed.
Example:
{{ " Hello world "|rstrip }} => " Hello world"
sha_1
str → str
Converts the given value into a sha1 hash. Returns an empty string on error.
sha_256
str → str
Converts the given value into a sha256 hash. Returns an empty string on error.
size
str, list → int
Runs the python len() function on the input. If a string is provided, returns the number of characters. If a list is provided, returns the number of items.
Alias: count, length
slice
List[Any] | str → List[Any]
Returns a slice of the given list. Uses the same syntax as Python list slicing.
Learn more in the Django docs.
Example:
{{ ['a', 'b', 'c']|slice:":2" }} => ['a', 'b']
sort
list | Optional[str] → list
Given a list, returns it in sorted ascending order. This is case-sensitive. If a property is provided, it will sort the list of objects by the property.
Example:
{{ [3,3,-1,2]|sort }} => [-1,2,3,3]
{{ [{"name":"b"},{"name":"a"}]|sort:"name" }} => [{"name":"a"},{"name":"b"}]
sort_natural
list | Optional[str] → list
Given a list, returns it in sorted ascending order. This is case-insensitive. If a property is provided, it will sort the list of objects by the property.
This should not be used for sorting numbers.
Example:
{{ [{"name":"B"},{"name":"a"}]|sort_natural:"name" }} => [{"name":"a"},{"name":"B"}]
split
str | Optional[str] → List[str]
Splits a string into a list of substrings based on a given separator.
Example:
{{ "apple,orange,banana"|split:"," }}
strip
str → str
Given a string, returns it with any leading and trailing whitespace removed.
Example:
{{ " Hello world "|strip }} => "Hello world"
strip_html
str → list[str]
Given a string, returns it with all HTML tags removed.
Alias: striptags
Example:
{{ "<html>Hello world</html>"|strip_html }} => "Hello world"
strip_newlines
str → str
Given a string, returns it with all newlines removed.
Example:
{{ "Hello\nWorld\r\n"|strip_newlines }} => "HelloWorld"
sum_list
List[int, float] → float
Sums all the values in a list.
Example:
{{ [1,2,3,4,5]|sum_list }} => 15.0
title
str → str
Converts the given string to title case, i.e., capitalizes the first letter of each word.
Learn more in the Django docs.
Example:
{{ "mY FIRST poST"|title }} => "My First Post"
trim_slash
str → str
Removes a trailing slash in the given string.
Example:
{{ "https://domain.com/"|trim_slash }} => https://domain.com
truncate
str | int → str
Given a string, returns a string that is truncated with an ellipsis appended. The default truncated length is 50 characters.
Example:
{{ "Hello world"|truncate }} => "Hello world"
{{ "Hello world"|truncate:5 }} => "Hello…"
uniq
list | Optional[str] → list
Given a list, returns a list without any duplicates. If a property is provided, it will remove duplicates based on the property.
Example:
{{ [3,1,2,2]|uniq }} => [3,1,2]
{{ [{"name":"a"},{"name":"B"},{"name":"a"}]|uniq:"name" }} => [{"name":"a"},{"name":"B"}]
upcase
str → str
Given a string, returns it with all characters in uppercase.
Alias: upper
upper
str → str
Converts the given string into all uppercase characters.
Learn more in the Django docs.
Example:
{{ "mY FIRST poST"|upper }} => "MY FIRST POST"
urldecode
str → str
URL-decodes the given string.
Example:
{{ %5BHello%20World%5D|urldecode }} => '[Hello World]'
urldecodeplus
str → str
URL-decodes the given string and also replaces plus signs with spaces.
Example:
{{ %5BHello+World%5D|urldecode }} => '[Hello World]'
urlencode
str | str → str
URL-encodes the given string.
An optional argument containing the characters which should not be escaped can be provided.
If not provided, the / character is assumed safe. An empty string can be provided when all characters should be escaped.
Learn more in the Django docs.
Example:
{{ '[Hello / World]'|urlencode }} => "%5BHello%20/%20World%5D"
{{ '[Hello / World]'|urlencode:'' }} => "%5BHello%20%2F%20World%5D"
{{ '[Hello / World]'|urlencode:'/ []' }} => "[Hello / World]"
urlencodeplus
str | str → str
Similar to the urlencode filter but encodes spaces using the + character as opposed to %20.
An optional argument containing the characters which should not be escaped can be provided.
If not provided, the / character is assumed safe. An empty string can be provided when all characters should be escaped.
Example:
{{ '[Hello / World]'|urlencodeplus }} => "%5BHello+/+World%5D"
{{ '[Hello / World]'|urlencodeplus:'' }} => "%5BHello+%2F+World%5D"
{{ '[Hello / World]'|urlencodeplus:'/ []' }} => "[Hello / World]"
Updated 9 months ago