HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides

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, floatint, float

Given a number, returns its absolute value.

Example:

{{ -1.2|abs }} => 1.2

append

str | strstr

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, floatint, 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, floatint, float

Given a number, returns the minimum of the number and the target value.

Example:

{{ 1|at_most:-1.0 }} => -1.0

base64_decode

strstr

Decodes the input from Base-64 format.

base64_encode

strstr

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

strstr

Decodes the input from Base-64 format with URL-safe characters.

base64_url_safe_encode

strstr

Encodes the input in Base-64 format with URL-safe characters. Any encoded + will be replaced with - and any / will be replaced with _.

capitalize

strstr

Given a string, returns it with the first character in uppercase.

Alias: capfirst

ceil

str, int, floatstr

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

listlist

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, liststr, 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, listint

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

strdatetime.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 | AnyAny

Supplies a default value to be used if the variable is empty.

Example:

{{ first_name|default:'friend' }}

dictfilter

List[dict] | strList[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, floatfloat

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

strstr

Given a string, returns it with all characters in lowercase.

Alias: lower

escape

strstr

Escapes a string's HTML. Specifically, it makes these replacements:

  • < is converted to &lt;.
  • > is converted to &gt;.
  • ' (single quote) is converted to &#x27;.
  • " (double quote) is converted to &quot;.
  • & is converted to &amp;.

Learn more in the Django docs.

Example:

{{ html_string|escape }}

escape_once

strstr

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 }} => "&lt;p&gt;Hello&lt;/p&gt;"
{{ "&lt;p&gt;Hello & World&lt;/p&gt;"|escape_once }} => "&lt;p&gt;Hello &amp; World&lt;/p&gt;"

find_replace

str | strstr

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, floatfloat, 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 | intfloat

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, floatfloat, 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, floatstr

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

Formats a date variable as a string following this format: Feb. 11, 2016, 4:46 p.m.

httpize

strstr

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

strstr

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] | strstr

Joins a list with a string.

Example:

{{ ['a', 'b', 'c']|join:" & " }} => "a & b & c"

length

str, listint

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 | strlist

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, intAny

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

strstr

Given a string, returns it with any leading whitespace removed.

Example:

{{ " Hello world "|lstrip }} => "Hello world "

map

list | strlist

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

strstr

Converts the given value into an md5 hash. Returns an empty string on error.

minus

int, str, float | int, str, floatfloat, str

Subtracts a number by a given number. If any error occurs, the return value is an empty string "".

Alias: floatsub

missing_image

strstr

If a provided image is invalid, supplies a blank image, so that no error displays.

missing_product_image

strstr

If a provided product image url is blank, supplies a placeholder image.

modulo

int, str | int, strfloat

Returns the remainder of x divided by y.

Alias: remainder

multiply

str, int, float | str, int, floatfloat

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

strstr

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 | intstr

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, floatfloat, str

Adds a number to the variable's value. If any error occurs, the return value is an empty string "".

Alias: floatadd

prepend

str | strstr

Given a string, returns a string with the target string prepended to it.

Example:

{{ "hello"|prepend:"world " }} => "world hello"

remainder

int, str | int, strfloat

Returns the remainder of x divided by y.

Example:

{{ 5|remainder:2 }} => 1.0
{{ 6|remainder:2 }} => 0.0

remove

str | strstr

Given a string, returns a string with all occurrences of the target substring removed.

Example:

{{ "hello world, hello"|remove:"hello" }} => " world, "

remove_first

str | strstr

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 | strstr

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 | strstr

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 | strstr

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 | strstr

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 | strList[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

listlist

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, floatstr

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

strstr

Given a string, returns it with any trailing whitespace removed.

Example:

{{ " Hello world "|rstrip }} => " Hello world"

sha_1

strstr

Converts the given value into a sha1 hash. Returns an empty string on error.

sha_256

strstr

Converts the given value into a sha256 hash. Returns an empty string on error.

size

str, listint

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] | strList[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

strstr

Given a string, returns it with any leading and trailing whitespace removed.

Example:

{{ "    Hello world "|strip }} => "Hello world"

strip_html

strlist[str]

Given a string, returns it with all HTML tags removed.

Alias: striptags

Example:

{{ "<html>Hello world</html>"|strip_html }} => "Hello world"

strip_newlines

strstr

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

strstr

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

strstr

Removes a trailing slash in the given string.

Example:

{{ "https://domain.com/"|trim_slash }} => https://domain.com

truncate

str | intstr

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

strstr

Given a string, returns it with all characters in uppercase.

Alias: upper

upper

strstr

Converts the given string into all uppercase characters.

Learn more in the Django docs.

Example:

{{ "mY FIRST poST"|upper }} => "MY FIRST POST"

urldecode

strstr

URL-decodes the given string.

Example:

{{ %5BHello%20World%5D|urldecode }} => '[Hello World]'

urldecodeplus

strstr

URL-decodes the given string and also replaces plus signs with spaces.

Example:

{{ %5BHello+World%5D|urldecode }} => '[Hello World]'

urlencode

str | strstr

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 | strstr

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