Filters

The following filters are available to Twig templates in Craft:

Filter Description
abs Returns the absolute value of a number.
append Appends HTML to the end of another element.
ascii Converts a string to ASCII characters.
atom Converts a date to an ISO-8601 timestamp.
attr Modifies an HTML tag’s attributes.
batch Batches items in an array.
camel Formats a string into camelCase.
capitalize Capitalizes the first character of a string.
column Returns the values from a single property or key in an array.
contains Returns whether an array contains a nested item with a given key/value pair.
convert_encoding Converts a string from one encoding to another.
currency Formats a number as currency.
date Formats a date.
date_modify Modifies a date.
datetime Formats a date with its time.
default Returns the value or a default value if empty.
diff Returns the difference between arrays.
duration Returns a DateInterval object.
encenc Encrypts and base64-encodes a string.
escape Escapes a string.
explodeClass Converts a class attribute value into an array of class names.
explodeStyle Converts a style attribute value into an array of property name/value pairs.
filesize Formats a number of bytes into something else.
filter Filters the items in an array.
first Returns the first character/item of a string/array.
format Formats a string by replacing placeholders.
group Groups items in an array.
hash Prefixes a string with a keyed-hash message authentication code (HMAC).
id Normalizes an element ID into only alphanumeric characters, underscores, and dashes.
indexOf Returns the index of a given value within an array, or the position of a passed-in string within another string.
index Indexes the items in an array.
intersect Returns the intersecting items of two arrays.
join Concatenates multiple strings into one.
json_decode JSON-decodes a value.
json_encode JSON-encodes a value.
kebab Formats a string into “kebab-case”.
keys Returns the keys of an array.
last Returns the last character/item of a string/array.
lcfirst Lowercases the first character of a string.
length Returns the length of a string or array.
literal Escapes an untrusted string for use with element query params.
lower Lowercases a string.
map Applies an arrow function to the items in an array.
markdown Processes a string as Markdown.
merge Merges an array with another array
multisort Sorts an array by one or more keys within its sub-arrays.
namespace Namespaces input names and other HTML attributes, as well as CSS selectors.
namespaceInputId Namespaces an element ID.
namespaceInputName Namespaces an input name.
nl2br Replaces newlines with <br> tags.
number Formats a number.
number_format Formats numbers.
parseRefs Parses a string for reference tags.
pascal Formats a string into “PascalCase”.
percentage Formats a percentage.
prepend Prepends HTML to the beginning of another element.
purify Runs HTML code through HTML Purifier.
push Appends one or more items onto the end of an array.
raw Marks as value as safe for the current escaping strategy.
reduce Iteratively reduces a sequence or mapping to a single value.
replace Replaces parts of a string with other things.
reverse Reverses a string or array.
round Rounds a number.
rss Converts a date to RSS date format.
slice Extracts a slice of a string or array.
snake Formats a string into “snake_case”.
sort Sorts an array.
spaceless Removes whitespace between HTML tags.
split Splits a string by a delimiter.
striptags Strips SGML/XML tags from a string.
time Formats a time.
timestamp Formats a human-readable timestamp.
title Formats a string into “Title Case”.
translate Translates a message.
truncate Truncates a string to a given length, while ensuring that it does not split words.
trim Strips whitespace from the beginning and end of a string.
ucfirst Capitalizes the first character of a string.
unique Removes duplicate values from an array.
unshift Prepends one or more items to the beginning of an array.
upper Formats a string into “UPPER CASE”.
url_encode Percent-encodes a string as a URL segment or an array as a query string.
values Returns all the values in an array, resetting its keys.
where Filters an array by key/value pairs.
withoutKey Returns an array without the specified key.
without Returns an array without the specified element(s).

# append

Appends HTML to the end of another element.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>') }}
{# Output: <div><p>Lorem</p><p>Ipsum</p></div> #}

If you only want to append a new element if one of the same type doesn’t already exist, pass 'keep' as a second argument.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>', 'keep') }}
{# Output: <div><p>Lorem</p></div> #}

If you want to replace an existing element of the same type, pass 'replace' as a second argument.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>', 'replace') }}
{# Output: <div><p>Ipsum</p></div> #}

# ascii

Converts a string to ASCII characters.

{{ 'über'|ascii }}
{# Output: uber #}

By default, the current site’s language will be used when choosing ASCII character mappings. You can override that by passing in a different locale ID.

{{ 'über'|ascii('de') }}
{# Output: ueber #}

# atom

Converts a date to an ISO-8601 timestamp (e.g. 2019-01-29T10:00:00-08:00), which should be used for Atom feeds, among other things.

{{ entry.postDate|atom }}

# attr

Modifies an HTML tag’s attributes, using the same attribute definitions supported by using yii\helpers\BaseHtml::renderTagAttributes().

{% set tag = '<div>' %}
{{ tag|attr({
    class: 'foo'
}) }}
{# Output: <div class="foo"> #}

Only the first tag will be modified, and any HTML comments or doctype declarations before it will be ignored.

{% set svg %}
    <?xml version="1.0" encoding="utf-8"?>
    <svg>...</svg>
{% endset %}
{{ svg|attr({
    class: 'icon'
}) }}
{# Output:
   <?xml version="1.0" encoding="utf-8"?>
   <svg class="icon">...</svg> #}

Attributes can be removed by setting them to false.

{% set tag = '<input type="text" disabled>' %}
{{ tag|attr({
    disabled: false
}) }}
{# Output: <input type="text"> #}

class and style attributes will be combined with the element’s existing attributes, if set.

{% set tag = '<div class="foo" style="color: black;">' %}
{{ tag|attr({
    class: 'bar',
    style: {background: 'red'}
}) }}
{# Output: <div class="foo bar" style="color: black; background: red;"> #}

All other attributes will replace the existing attribute values.

{% set tag = '<input type="text">' %}
{{ tag|attr({
    type: 'email'
}) }}
{# Output: <input type="email"> #}

If you want to completely replace a class or style attribute, remove it first, then set the new value:

{% set tag = '<div class="foo">' %}
{{ tag|attr({class: false})|attr({class: 'bar'}) }}
{# Output: <div class="bar"> #}

# camel

Returns a string formatted in “camelCase”.

{{ 'foo bar'|camel }}
{# Output: fooBar #}

# column

Returns the values from a single property or key in the input array.

{% set entryIds = entries|column('id') %}

An arrow function can be passed instead, if the values that should be returned don’t exist as a property or key on the array elements.

{% set authorNames = entries|column(e => e.author.fullName) %}

This works similarly to Twig’s core column filter, except that ArrayHelper::getColumn() is used rather than PHP’s array_column() function.

# contains

Returns whether the passed-in array contains any nested arrays/objects with a particular key/attribute set to a given value.

{% set works = craft.entries()
    .section('artwork')
    .all() %}

{# See if any of the artwork has a mature rating #}
{% if works|contains('rating', 'm') %}
    <p class="mature">Some of this artwork is meant for mature viewers.</p>
{% endif %}

# currency

Formats a number with a given currency according to the user’s preferred language.

{{ 1000000|currency('USD') }}
{# Output: $1,000,000.00 #}

You can pass stripZeros=true to remove any fraction digits if the value to be formatted has no minor value (e.g. cents):

{{ 1000000|currency('USD', stripZeros=true) }}
{# Output: $1,000,000 #}

# date

Formats a timestamp or DateTime object.

{{ entry.postDate|date }}
{# Output: Dec 20, 1990 #}

You can customize how the date is presented by passing a custom date format, just like Twig’s core date filter:

{{ 'now'|date('m/d/Y') }}
{# Output: 12/20/1990 #}

Craft also provides some special format keywords that will output locale-specific date formats:

Format Example
short 12/20/1990
medium (default) Dec 20, 1990
long December 20, 1990
full Thursday, December 20, 1990
{{ entry.postDate|date('short') }}
{# Output: 12/20/1990 #}

The current application locale will be used by default. If you want to format the date for a different locale, use the locale argument:

{{ entry.postDate|date('short', locale='en-GB') }}
{# Output: 20/12/1990 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|date('short', timezone='UTC') }}
{# Output: 12/21/1990 #}

If the value passed to the date filter is null, it will return the current date by default.

# datetime

Formats a timestamp or DateTime object, including the time of day.

{{ entry.postDate|datetime }}
{# Output: Dec 20, 1990, 5:00:00 PM #}

Craft provides some special format keywords that will output locale-specific date and time formats:

{{ entry.postDate|datetime('short') }}
{# Output: 9/26/2018, 5:00 PM #}

Possible format values are:

Format Example
short 12/20/1990, 5:00 PM
medium (default) Dec 20, 1990, 5:00:00 PM
long December 20, 1990 at 5:00:00 PM PDT
full Thursday, December 20, 1990 at 5:00:00 PM PDT

The current application locale will be used by default. If you want to format the date and time for a different locale, use the locale argument:

{{ entry.postDate|datetime('short', locale='en-GB') }}
{# Output: 20/12/1990, 17:00 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|datetime('short', timezone='UTC') }}
{# Output: 12/21/1990, 12:00 AM #}

# diff

Returns the difference between arrays, using array_diff().

It will return a new array with any values that were in the initial array, which weren’t present in any of the arrays passed into the filter.

{% set arr1 = ['foo', 'bar'] %}
{% set arr2 = ['bar', 'baz'] %}
{% set arr3 = arr1|diff(arr2) %}
{# Result: ['foo'] #}

# duration

Runs a DateInterval object through craft\helpers\DateTimeHelper::humanDurationFromInterval()

<p>Posted {{ entry.postDate.diff(now)|duration(false) }} ago.</p>

# encenc

Encrypts and base64-encodes a string.

{{ 'secure-string'|encenc }}

# explodeClass

Converts a class attribute value into an array of class names.

If an array is passed in, it will be returned as-is.

{% set classNames = 'foo bar baz'|explodeClass %}
{# Result: ['foo', 'bar', 'baz'] #}

# explodeStyle

Converts a style attribute value into an array of property name/value pairs.

If an array is passed in, it will be returned as-is.

{% set styles = 'font-weight: bold; color: red;'|explodeStyle %}
{# Result: {'font-weight': 'bold', 'color': 'red'} #}

# filesize

Formats a number of bytes into something nicer.

{{ asset.size }}
{# Output: 1944685 #}
{{ asset.size|filesize }}
{# Output: 1.945 MB #}

# filter

Filters elements of an array.

If nothing is passed to it, any “empty” elements will be removed.

{% set array = ['foo', '', 'bar', '', 'baz'] %}
{% set filteredArray = array|filter %}
{# Result: ['foo', 'bar', 'baz'] #}

When an arrow function is passed, this works identically to Twig’s core filter filter.

{% set array = ['foo', 'bar', 'baz'] %}
{% set filteredArray = array|filter(v => v[0] == 'b') %}
{# Result: ['bar', 'baz'] #}

# group

Groups items in an array by a the results of an arrow function.

{% set allEntries = craft.entries.section('blog').all() %}
{% set allEntriesByYear = allEntries|group(e => e.postDate|date('Y')) %}

{% for year, entriesInYear in allEntriesByYear %}
    <h2>{{ year }}</h2>

    <ul>
        {% for entry in entriesInYear %}
            <li><a href="{{ entry.url }}">{{ entry.title }}</a></li>
        {% endfor %}
    </ul>
{% endfor %}

# hash

Prefixes the given string with a keyed-hash message authentication code (HMAC), for securely passing data in forms that should not be tampered with.

<input type="hidden" name="foo" value="{{ 'bar'|hash }}">

PHP scripts can validate the value via Security::validateData():

$foo = Craft::$app->request->getBodyParam('foo');
$foo = Craft::$app->security->validateData($foo);

if ($foo !== false) {
    // data is valid
}

# id

Formats a string into something that will work well as an HTML input id, via craft\web\View::formatInputId().

{% set name = 'input[name]' %}
<input type="text" name="{{ name }}" id="{{ name|id }}">

# index

Runs an array through ArrayHelper::index().

{% set entries = entries|index('id') %}

# indexOf

Returns the index of a passed-in value within an array, or the position of a passed-in string within another string. (Note that the returned position is 0-indexed.) If no position can be found, -1 is returned instead.

{% set colors = ['red', 'green', 'blue'] %}
<p>Green is located at position {{ colors|indexOf('green') + 1 }}.</p>

{% set position = 'team'|indexOf('i') %}
{% if position != -1 %}
    <p>There <em>is</em> an “i” in “team”! It’s at position {{ position + 1 }}.</p>
{% endif %}

# intersect

Returns an array containing only the values that are also in a passed-in array.

{% set ownedIngredients = [
    'vodka',
    'gin',
    'triple sec',
    'tonic',
    'grapefruit juice'
] %}

{% set longIslandIcedTeaIngredients = [
    'vodka',
    'tequila',
    'rum',
    'gin',
    'triple sec',
    'sweet and sour mix',
    'Coke'
] %}

{% set ownedLongIslandIcedTeaIngredients =
    ownedIngredients|intersect(longIslandIcedTeaIngredients)
%}

# json_encode

Returns the JSON representation of a value.

This works similarly to Twig’s core json_encode filter, except that the options argument will default to JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_QUOT if the response content type is either text/html or application/xhtml+xml.

# json_decode

JSON-decodes a string into an array by passing it through yii\helpers\Json::decode().

{% set arr = '[1, 2, 3]'|json_decode %}

# kebab

Returns a string formatted in “kebab-case”.

That’s a reference to shish kebabs for those of you that don’t get the analogy.

{{ 'foo bar?'|kebab }}
{# Output: foo-bar #}

# lcfirst

Lowercases the first character of a string.

{{ 'Foobar'|lcfirst }}
{# Output: foobar #}

# literal

Runs a string through craft\helpers\Db::escapeParam().

{{ 'SELECT id, * FROM table'|literal }}
{# Output: SELECT id\, \* FROM table #}

# markdown or md

Processes a string with Markdown.

{% set content %}
# Everything You Need to Know About Computer Keyboards

The only *real* computer keyboard ever made was famously
the [Apple Extended Keyboard II] [1].

    [1]: https://www.flickr.com/photos/gruber/sets/72157604797968156/
{% endset %}

{{ content|markdown }}

This filter supports two arguments:

  • flavor can be 'original' (default value), 'gfm'(GitHub-Flavored Markdown), 'gfm-comment' (GFM with newlines converted to <br>s), or 'extra' (Markdown Extra)
  • inlineOnly determines whether to only parse inline elements, omitting any <p> tags (defaults to false)

# multisort

Sorts an array by one or more properties or keys within an array’s values.

To sort by a single property or key, pass its name as a string:

{% set entries = entries|multisort('title') %}

To sort by multiple properties or keys, pass them in as an array. For example, this will sort entries by their post date first, and then by their title:

{% set entries = entries|multisort(['postDate', 'title']) %}

An arrow function can be passed instead, if the values that should be sorted by don’t exist as a property or key on the array elements.

{% set entries = entries|multisort(e => e.author.fullName) %}

The values will be sorted in ascending order by default. You can switch to descending order with the direction param:

{% set entries = entries|multisort('title', direction=SORT_DESC) %}

You can also customize which sorting behavior is used, with the sortFlag param. For example, to sort items numerically, use SORT_NUMERIC:

{% set entries = entries|multisort('id', sortFlag=SORT_NUMERIC) %}

See PHP’s sort() documentation for the available sort flags.

When sorting by multiple properties or keys, you must set the direction and sortFlag params to arrays as well.

{% set entries = entries|multisort([
    'postDate',
    'title',
], sortFlag=[SORT_NATURAL, SORT_FLAG_CASE]) %}

# namespace

The |namespace filter can be used to namespace input names and other HTML attributes, as well as CSS selectors.

For example, this:

{% set html %}
<style>
  .text { font-size: larger; }
  #title { font-weight: bold; }
</style>
<input class="text" id="title" name="title" type="text">
{% endset %}
{{ html|namespace('foo') }}

would become this:

<style>
  .text { font-size: larger; }
  #foo-title { font-weight: bold; }
</style>
<input class="text" id="foo-title" name="foo[title]" type="text">

Notice how the #title CSS selector became #foo-title, the id attribute changed from title to foo-title, and the name attribute changed from title to foo[title].

If you want class names to get namespaced as well, pass withClasses=true. That will affect both class CSS selectors and class attributes:

{{ html|namespace('foo', withClasses=true) }}

That would result in:


 


 

<style>
  .foo-text { font-size: larger; }
  #foo-title { font-weight: bold; }
</style>
<input class="foo-text" id="foo-title" name="foo[title]" type="text">

# namespaceInputId

Namepaces an element ID.

For example, this:

{{ 'bar'|namespaceInputId('foo') }}

would output:

foo-bar

If this is used within a namespace tag, the namespace applied by the tag will be used by default.

# namespaceInputName

Namepaces an input name.

For example, this:

{{ 'bar'|namespaceInputName('foo') }}

would output:

foo[bar]

If this is used within a namespace tag, the namespace applied by the tag will be used by default.

# number

Formats a number according to the user’s preferred language.

You can optionally pass false to it if you want group symbols to be omitted (e.g. commas in English).

{{ 1000000|number }}
{# Output: 1,000,000 #}

{{ 1000000|number(false) }}
{# Output: 1000000 #}

# parseRefs

Parses a string for reference tags.

{% set content %}
    {entry:blog/hello-world:link} was my first blog post. Pretty geeky, huh?
{% endset %}

{{ content|parseRefs|raw }}

# pascal

Returns a string formatted in “PascalCase” (AKA “UpperCamelCase”).

{{ 'foo bar'|pascal }}
{# Output: FooBar #}

# percentage

Formats a percentage according to the user’s preferred language.

# prepend

Prepends HTML to the beginning of another element.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>') }}
{# Output: <div><p>Lorem</p><p>Ipsum</p></div> #}

If you only want to append a new element if one of the same type doesn’t already exist, pass 'keep' as a second argument.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>', 'keep') }}
{# Output: <div><p>Ipsum</p></div> #}

If you want to replace an existing element of the same type, pass 'replace' as a second argument.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>', 'replace') }}
{# Output: <div><p>Lorem</p></div> #}

# purify

Runs the given text through HTML Purifier.

{{ user.bio|purify }}

You can specify a custom HTML Purifier config file as well:

{{ user.bio|purify('user_bio') }}

That will configure HTML Purifier based on the settings defined by config/htmlpurifier/user_bio.json.

# push

Appends one or more items onto the end of an array, and returns the new array.

{% set array1 = ['foo'] %}
{% set array2 = array|push('bar', 'baz') %}
{# Result: ['foo', 'bar', 'baz'] #}

# replace

Replaces parts of a string with other things.

When a mapping array is passed, this works identically to Twig’s core replace filter:

{% set str = 'Hello, FIRST LAST' %}

{{ str|replace({
    FIRST: currentUser.firstName,
    LAST:  currentUser.lastName
}) }}

Or you can replace one thing at a time:

{% set str = 'Hello, NAME' %}

{{ str|replace('NAME', currentUser.name) }}

You can also use a regular expression to search for matches by starting and ending the replacement string’s value with forward slashes:

{{ tag.title|lower|replace('/[^\\w]+/', '-') }}

# rss

Outputs a date in the format required for RSS feeds (D, d M Y H:i:s O).

{{ entry.postDate|rss }}

# snake

Returns a string formatted in “snake_case”.

{{ 'foo bar'|snake }}
{# Output: foo_bar #}

# time

Outputs the time of day for a timestamp or DateTime object.

{{ entry.postDate|time }}
{# Output: 10:00:00 AM #}

Craft provides some special format keywords that will output locale-specific time formats:

{{ entry.postDate|time('short') }}
{# Output: 10:00 AM #}

Possible format values are:

Format Example
short 5:00 PM
medium (default) 5:00:00 PM
long 5:00:00 PM PDT

The current application locale will be used by default. If you want to format the date and time for a different locale, use the locale argument:

{{ entry.postDate|time('short', locale='en-GB') }}
{# Output: 17:00 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|time('short', timezone='UTC') }}
{# Output: 12:00 AM #}

# timestamp

Formats a date as a human-readable timestamp, via craft\i18n\Formatter::asTimestamp().

{{ now|timestamp }}
{# Output: 9:00:00 AM #}

# translate or t

Translates a message with Craft::t().

{{ 'Hello world'|t('myCategory') }}

If no category is specified, it will default to site.

{{ 'Hello world'|t }}

See Static Message Translations for a full explanation on how this works.

# truncate

The truncate filter was added in Craft 3.5.10.

Truncates a string to a given length, while ensuring that it does not split words.

{{ 'Hello world'|truncate(10) }}
{# Output: Hello… #}

An ellipsis () will be appended to the string if it needs to be truncated, by default. You can customize what gets appended by passing a second argument. (Note that a longer appended string could result in more of the original string getting truncated.)

{{ 'Hello world'|truncate(10, '...') }}
{# Output: Hello... #}

{{ 'Hello world'|truncate(10, '') }}
{# Output: Hello #}

If the truncated string cuts down to less than a single word, that first word will be split by default.

{{ 'Hello world'|truncate(2) }}
{# Output: H… #}

If you’d prefer to have the entire word removed, set the splitSingleWord argument to false.

{{ 'Hello world'|truncate(2, splitSingleWord=false) }}
{# Output: … #}

# ucfirst

Capitalizes the first character of a string.

{{ 'foobar'|ucfirst }}
{# Output: Foobar #}

# unique

Runs an array through array_unique().

{% set array = ['Larry', 'Darryl', 'Darryl'] %}
{{ array|unique }}
{# Result: ['Larry', 'Darryl'] #}

# unshift

Prepends one or more items to the beginning of an array, and returns the new array.

{% set array1 = ['foo'] %}
{% set array2 = array|unshift('bar', 'baz') %}
{# Result: ['bar', 'baz', 'foo'] #}

# values

Returns an array of all the values in a given array, but without any custom keys.

{% set arr1 = {foo: 'Foo', bar: 'Bar'} %}
{% set arr2 = arr1|values %}
{# arr2 = ['Foo', 'Bar'] #}

# where

Runs an array through craft\helpers\ArrayHelper::where().

{% set array = { 'foo': 'bar', 'bar': 'baz', 'bat': 'bar' } %}
{{ array|filterByValue(v => v == 'bar') }}
{# Result: { 'foo': 'bar', 'bat': 'bar' } #}

# without

Returns an array without the specified element(s).

{% set entries = craft.entries.section('articles').limit(3).find %}
{% set firstEntry = entries[0] %}
{% set remainingEntries = entries|without(firstEntry) %}

# withoutKey

Returns an array without the specified key.

{% set array = {
    foo: 'foo',
    bar: 'bar',
    baz: 'baz'
} %}
{% set filtered = array|withoutKey('baz') %}