Filters affect the ultimate output of your HubL. They can be applied to various HubL statements and expressions to alter the template markup outputted by the server.
The basic syntax of a filter is |filtername. The filter is added directly following the statement or the expression, within its delimiters. Some filters have additional parameters that can be added in parentheses. The basic syntax of a filter with a string, a number, and a boolean parameters is: |filtername("stringParameter", 10, true). Notice that string parameters should be written in quotes. Also note that HubL filters have an alias that can be used to serve the same purpose as the primary filter.
The following article contains all of the supported HubL filters.
Please note:You can apply HubL filters to personalization tokens, such as contact and company tokens, on HubSpot CMS and blog pages, but not in emails. abs
Gets the absolute value of a number. You can use this filter to ensure that a number is positive.
add
Adds a numeric value to another numeric value. This filter functions the same as the + operator. The parameter in parentheses is the addend that you are combining with your initial numeric value.
attr
Renders the attribute of a dictionary. This filter is the equivalent of printing a variable that exists within a dictionary, such as content.absolute_url.
batch
Groups items within a sequence.
In the example below, there is a variable containing a sequence of types of fruits. The batch filter is applied to a loop that iterates through the sequence. The nested loop runs three times to print 3 types of fruit per row, before the outer loop runs again. Notice in the final output that since there are only 5 types of fruit, the final item is replaced by a (the second parameter).
between_times
Calculates the time between two datetime objects in a specified time unit.
Please note:You should use this filter only with variables that return a date. Starting September 30, 2024, this filter will no longer return the current date when a null value is passed. After that date, a null value in the filter will return September 30, 2024.
bool
Converts a text string value to a boolean.
capitalize
Capitalizes the first letter of a variable value. The first character will be uppercase, all others letters will be lowercased. Subsequent words separated by spaces or hyphens will not have their first letter uppercased.
center
Centers text within a given field length using whitespace. This filter is not recommended or particularly useful since HubSpot’s HTML compiler will automatically strip out the white space; however, it is included here for the sake of comprehensiveness.
The example below shows this filter being applied to a variable in a pre tag, so the whitespace isn’t stripped out.
convert_rgb
Converts a HEX value to an RGB string. This is useful if you need to convert color variables to RGB to be used with a RGBA CSS declaration. In the example below, the value set by a color module is converted to an RGB value and used in an RGBA CSS declaration.
cut
Removes a string from a value. This filter can be used to match and cut out a specific part of a string. The parameter specifies the part of the string that should be removed. The example below removes the space and the word world from the original variable value.
default
If the value is undefined it will return the first parameter, otherwise the value of the variable will be printed. If you want to use default with variables that evaluate to false, you have to set the second parameter to true.
The first example below would print the message if the variable is not defined. The second example applies the filter to an empty string, which is not undefined, but it prints a message due to the second parameter.
dictsort
Sort a dict and yield (key, value) pairs. Dictionaries are unsorted by default, but you can print a dictionary, sorted by key or value. The first parameter is a boolean to determine, whether or not the sorting is case sensitive. The second parameter determines whether to sort the dict by key or value. The example below prints a sorted contact dictionary, with all the known details about the contact.
difference
Returns the difference of two sets or lists. The list returned from the filter contains all unique elements that are in the first list but not the second.
divide
Divides the current value by a divisor. The parameter passed is the divisor. This filter is an alternative to the / operator.
divisible
An alternative to the divisibleby expression test, this filter will evaluate to true if the value is divisible by the given number.
escape_html
Escapes the content of an HTML input. Accepts a string and converts the characters &, <, >, ‘, ”, and escape_jinjava into HTML-safe sequences. Use this filter for HubL variables that are used in HTML but should not allow any HTML.
escape_attr
Escapes the content of an HTML attribute input. Accepts a string and converts the characters &, <, ‘, ”, and escape_jinjava into HTML-safe sequences. Use this filter for HubL variables that are being added to HTML attributes.
Note that when escaping values of attributes that accept URLs, such as href, you should use the escape_url filter instead.
escape_jinjava
Converts the characters { and } in strings to Jinjava-safe sequences. Use this filter if you need to display text that might contain such characters in Jinjava.
escape_js
Escapes strings, including escape_jinjava, so that they can be safely inserted into a JavaScript variable declaration. Use this filter for HubL variables that are used inside HTML script elements.
escape_url
Escapes the content of a URL input, enforcing specified protocols, sanitizing invalid and dangerous characters, and encoding HTML entities. Use this filter for HubL variables that are used within HTML attributes that should be valid URLs.
escapejson
Escapes strings so that they can be used as JSON values.
Formats a number value into a human-readable file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). By default, decimal prefixes are used (e.g., MB and GB), but you can set the binary parameter to true to use binary prefixes such as Mebi (MiB) and Gibi (GiB).
first
Returns the first item in a sequence.
float
Converts a value into a floating point number. If the conversion doesn’t work it will return 0.0. You can override this default using the first parameter.
forceescape
Strictly enforces HTML escaping. In HubSpot’s environment there isn’t really a use case for double escaping, so this is generally behaves the same as the escape filter.
Applies Python string formatting to an object. %s can be replaced with another variable.
Formats a given number as a currency based on portal’s default currency and locale passed in as a parameter. Replaces the deprecated format_currency filter.
Formats the date component of a date object.
Please note:You should use this filter only with variables that return a date. Starting September 30, 2024, this filter will no longer return the current date when a null value is passed. After that date, a null value in the filter will return September 30, 2024.
Please note:You should use this filter only with variables that return a date. Starting September 30, 2024, this filter will no longer return the current date when a null value is passed. After that date, a null value in the filter will return September 30, 2024.
Please note:You should use this filter only with variables that return a date. Starting September 30, 2024, this filter will no longer return the current date when a null value is passed. After that date, a null value in the filter will return September 30, 2024.
fromjson
Converts a JSON string to an object.
geo_distance
Calculates the ellipsoidal 2D distance between two points on Earth.
groupby
Groups a sequence of objects by a common attribute. The parameter sets the common attribute to group by.
indent
Indents text within a given field length using whitespace. This filter is not recommended or particularly useful because HubSpot’s HTML compiler will automatically strip out the white space. However, it is included here for the sake of comprehensiveness.
The example below shows an indent filter being applied to a variable in a <pre> tag, so the whitespace isn’t stripped out. The first parameter controls the amount of whitespace and the second boolean toggles whether to indent the first line.
int
Converts the value into an integer. If the conversion doesn’t work it will return 0. You can override this default using the first parameter.
intersect
Returns the intersection of two sets or lists. The list returned from the filter contains all unique elements that are contained in both lists.
ipaddr
Evaluates to true if the value is a valid IPv4 or IPv6 address.
join
Returns a string which is the concatenation of the strings in the sequence. The separator between elements is an empty string per default, you can define it with the optional parameter. The second parameter can be used to specify an attribute to join.
last
Returns the last item of a sequence.
length
Returns the number of items of a sequence or mapping.
list
Converts values into a list. Strings will be returned as separate characters unless contained in square bracket sequence delimiters [ ].
log
Calculates the natural logarithm of a number.
lower
Converts all letters in a value to lowercase.
map
Applies a filter on a sequence of objects or looks up an attribute. This is useful when dealing with a list of objects where you’re only interested in a certain value of it.
The basic usage is mapping on an attribute. For example, if you want to use conditional logic to check if a value is present in a particular attribute of a dict. Alternatively, you can let it invoke a filter by passing the name of the filter and the arguments afterwards.
md5
Calculates the md5 hash of the given object.
minus_time
Subtracts an amount of time from a datetime object.
multiply
Multiplies a value with a number. Functions the same as the * operator.
plus_time
Adds an amount of time to a datetime object.
pprint
Pretty print a variable. This prints the type of variable and other info that is useful for debugging.
random
Return a random item from the sequence.
Please note:When using this filter, the page will be prerendered periodically rather than every time the page content is updated. This means that the filtered content will not be updated on every page reload.This may not be an issue for certain types of content, such as displaying a random list of blog posts. However, if you need content to change randomly on every page load, you should instead use JavaScript to randomize the content client-side. regex_replace
Searches for a regex pattern and replaces with a sequence of characters. The first argument is a RE2-style regex pattern, the second is the replacement string.
Learn more about RE2 regex syntax.
reject
Filters a sequence of objects by applying an expression test to the object and rejecting the ones with the test succeeding.
rejectattr
Filters a sequence of objects by applying a test to an attribute of an object and rejecting the ones with the test succeeding.
render
Renders strings containing HubL early so that the output can be passed into other filters.
replace
Replaces all instances of a substring with a new one.
reverse
Reverses the object or return an iterator the iterates over it the other way round. To reverse a list use .reverse()
root
Calculates the square root of a value.
round
Rounds a number to a given precision.
safe
Mark a value as safe which means that in an environment with automatic escaping enabled this variable will not be escaped.
sanitize_html
Sanitizes the content of an HTML input for the output of rich text content. Accepts a string, then strips HTML tags that are not allowed. Use this filter for HubL variables that are used in HTML that should allow safe HTML.
You can include the following parameters to allow specific types of HTML tags: FORMATTING, BLOCKS, STYLES, LINKS, TABLES, IMAGES. For example, sanitize_html(IMAGES).
Using sanitize_html will include all parameters in the filter.
You can also include a STRIP parameter to strip all HTML. All content is run through escape_jinjava as well to prevent nested interpretation.
select
Filters a sequence of objects by applying a test to the objects and only selecting the ones with the test succeeding.
selectattr
Filters a sequence of objects by applying a test to an attribute of the objects and only selecting the ones with the test succeeding.
shuffle
Randomizes the order of iteration through a sequence. The example below shuffles a standard blog loop.
Please note:When using this filter, the page will be prerendered periodically rather than every time the page content is updated. This means that the filtered content will not be updated on every page reload.This may not be an issue for certain types of content, such as displaying a random list of blog posts. However, if you need content to change randomly on every page load, you should instead use JavaScript to randomize the content client-side. slice
Slices an iterator and returns a list of lists containing those items. The first parameter specifies how many items will be sliced, and the second parameter specifies characters to fill in empty slices.
sort
Sorts an iterable. This filter requires all parameters to sort by an attribute in HubSpot. The first parameter is a boolean to reverse the sort order. The second parameter determines whether or not the sorting is case sensitive. And the final parameter specifies an attribute to sort by. In the example below, posts from a blog are rendered and alphabetized by name.
split
Splits the input string into a list on the given separator. The first parameter specifies the separator to split the variable by. The second parameter determines how many times the variable should be split. Any remaining items would remained group. In the example below, a string of names is split at the ; for the first four names.
string
Converts a different variable type to a string. In the example below, a integer is converted into a string (pprint is used to confirm the change in variable type).
Strips SGML/XML tags and replace adjacent whitespace by one space. This filter can be used to remove any HTML tags from a variable.
strtodate
Converts a date string and date format to a date object.
strtotime
Converts a datetime string and a datetime format into a datetime object.
sum
Adds numeric values in a sequence. The first parameter can specify an optional attribute and the second parameter sets a value to return if there is nothing in the variable to sum.
symmetric_difference
Returns the symmetric difference of two sets or lists. The list returned from the filter contains all unique elements that are in the first list but not the second, or are in the second list but not the first.
title
Returns a title case version of the value (i.e., words will start with uppercase letters but all remaining characters are lowercase).
tojson
Writes an object as a JSON string.
trim
Strips leading and trailing whitespace. HubSpot already trims whitespace from markup, but this filter is documented for the sake of comprehensiveness.
truncate
Cuts off text after a certain number of characters. The default is 255. HTML characters are included in this count.
Please note:Because this filter relies on the spaces between words to shorten strings, it may not work as expected for languages without spaces between characters, such as Japanese.
truncatehtml
Truncates a given string, respecting HTML markup (i.e. will properly close all nested tags). This will prevent a tag from remaining open after truncation. HTML characters do not count towards the character total.
Please note:Because this filter relies on the spaces between words to shorten strings, it may not work as expected for languages without spaces between characters, such as Japanese.
unescape_html
Converts text with HTML-encoded entities to their Unicode equivalents.
union
Returns the union of two sets or lists. The list returned from the filter contains all unique elements that are in either list.
unique
Extracts a unique set from a sequence or dict of objects. When filtering a dict, such as a list of posts returned by a function, you can specify which attribute is used to deduplicate items in the dict.
unixtimestamp
Converts a datetime object into a Unix timestamp.
Please note:You should use this filter only with variables that return a date. Starting September 30, 2024, this filter will no longer return the current date when a null value is passed. After that date, a null value in the filter will return September 30, 2024.
upper
Converts all letters in a value to uppercase.
urlencode
Escapes and URL encodes a string using UTF-8 formatting. Accepts both dictionaries and regular strings as well as pairwise iterables.
urldecode
Decodes encoded URL strings back to the original URL. Accepts both dictionaries and regular strings as well as pairwise iterables.
urlize
Converts URLs in plain text into clickable links. If you pass the filter an additional integer it will shorten the urls to that number. The second parameter is a boolean that dictates whether the link is rel="no follow". The final parameter lets you specify whether the link will open in a new tab.
wordcount
Counts the number of words in a string.
If the string contains HTML, use the striptags filter to get an accurate count.
wordwrap
Causes words to wrap at a given character count. This works best in a <pre> because HubSpot strips whitespace by default.
xmlattr
Creates an HTML/XML attribute string, based on the items in a dict. All values that are neither none nor undefined are automatically escaped. It automatically prepends a space in front of the item if the filter returned something unless the first parameter is false.
