Filters

The following filters (opens new window) are available to Twig templates in Craft.

Filter	Description
abs (opens new window)	Returns the absolute value of a number.
address	Formats an address.
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.
base64_decode	Decodes a base64 string.
base64_encode	Encodes a string as base64.
batch (opens new window)	Batches items in an array.
boolean	Coerces the passed value to a boolean.
camel	Formats a string into camelCase.
capitalize (opens new window)	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 (opens new window)	Converts a string from one encoding to another.
currency	Formats a number as currency.
date_modify (opens new window)	Modifies a date.
date	Formats a date.
datetime	Formats a date with its time.
default (opens new window)	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 (opens new window)	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 (opens new window)	Returns the first character/item of a string/array.
float	Coerces the passed value to a float.
format (opens new window)	Formats a string by replacing placeholders.
group	Groups items in an array.
hash	Prefixes a string with a keyed-hash message authentication code (HMAC).
httpdate	Converts a date to the HTTP format.
id	Normalizes an element ID into only alphanumeric characters, underscores, and dashes.
index	Indexes the items in an array.
indexOf	Returns the index of a given value within an array, or the position of a passed-in string within another string.
integer	Coerces the passed value to an integer.
intersect	Returns the intersecting items of two arrays.
join (opens new window)	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 (opens new window)	Returns the keys of an array.
last (opens new window)	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, or the count of a query.
literal	Escapes an untrusted string for use with element query params.
lower (opens new window)	Lowercases a string.
map (opens new window)	Applies an arrow function to the items in an array.
markdown	Processes a string as Markdown.
merge	Merges an array with another one.
money	Outputs a value from a Money object.
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.
namespaceAttributes	Namespaces `id` and other HTML attributes, as well as CSS selectors.
namespaceInputId	Namespaces an element ID.
namespaceInputName	Namespaces an input name.
nl2br (opens new window)	Replaces newlines with `<br>` tags.
number_format (opens new window)	Formats numbers.
number	Formats a number.
parseAttr	Parses an HTML tag to find its attributes.
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 (opens new window)	Marks as value as safe for the current escaping strategy.
reduce (opens new window)	Iteratively reduces a sequence or mapping to a single value.
removeClass	Removes a class (or classes) from the given HTML tag.
replace	Replaces parts of a string with other things.
reverse (opens new window)	Reverses a string or array.
round (opens new window)	Rounds a number.
rss	Converts a date to RSS date format.
slice (opens new window)	Extracts a slice of a string or array.
snake	Formats a string into “snake_case”.
sort (opens new window)	Sorts an array.
spaceless (opens new window)	Removes whitespace between HTML tags.
split (opens new window)	Splits a string by a delimiter.
string	Coerces the passed value to a string.
striptags (opens new window)	Strips SGML/XML tags from a string.
time	Formats a time.
timestamp	Formats a human-readable timestamp.
title (opens new window)	Formats a string into “Title Case”.
translate	Translates a message.
trim (opens new window)	Strips whitespace from the beginning and end of a string.
truncate	Truncates a string to a given length, while ensuring that it does not split words.
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 (opens new window)	Formats a string into “UPPER CASE”.
url_encode (opens new window)	Percent-encodes a string as a URL segment or an array as a query string.
ucwords	Uppercases the first character of each word in a string.
values	Returns all the values in an array, resetting its keys.
where	Filters an array by key-value pairs.
widont	Inserts a non-breaking space between the last two words of a string.
without	Returns an array without the specified element(s).
withoutKey	Returns an array without the specified key.

# `address`

Applies formatting to an Address.

{% set myAddress = currentUser.getAddresses()|first %}
{{ myAddress|address }}
{# Output:
  <p translate="no">
  <span class="address-line1">1234 Balboa Towers Circle</span><br>
  <span class="locality">Los Angeles</span>, <span class="administrative-area">CA</span> <span class="postal-code">92662</span><br>
  <span class="country">United States</span>
  </p>
#}

This calls Addresses::formatAddress() (opens new window), so you can optionally provide an array of options and even your own formatter (opens new window).

# `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. 2038-01-19T03:14:07+00:00), which should be used for Atom feeds, among other things.

{{ entry.postDate|atom }}

Pass false to prevent the date from being converted to the system’s timezone:

{{ entry.customDateFieldWithTimezone|atom(false) }}

# `attr`

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

{% 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"> #}

Attribute values are HTML-encoded automatically:

{% set tag = '<input type="text">' %}
{{ tag|attr({
  type: 'submit',
  value: 'Register & Subscribe →'
}) }}
{# Output: <input type="submit" value="Register &amp; Subscribe →"> #}

# `base64_decode`

Decodes a base64-encoded string. The encoded value can come from anywhere, as base64 is widely supported and its input and output is consistent across implementations.

{{ 'Q3JhZnQgQ01T' | base64_decode }}
{# -> Craft CMS #}

JavaScript uses the btoa() (opens new window) function to encode values as base64, and atob() (opens new window) to decode them.

# `base64_encode`

Encodes a value as base64. Base64 can be useful for making unpredictable strings or data URL-safe.

{{ 'Craft CMS' | base64_encode }}
{# -> Q3JhZnQgQ01T #}

If you intend to use the value in a style sheet or URI, consider the dataUrl() function, instead.

Encoding is not the same as encryption! The result may appear random, but is completely reversible. Read more about the principles and applications of base64 (opens new window) if you are unsure whether it is appropriate!

# `boolean`

Coerces the passed value to a boolean using PHP’s boolval() (opens new window) function. Useful when dealing with stronger typing in PHP 8 and Twig 3.x.

# `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 (opens new window) filter, except that ArrayHelper::getColumn() (opens new window) is used rather than PHP’s array_column() (opens new window) 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 #}

If the passed-in value isn’t a valid number it will be returned verbatim:

{{ 'oh hai'|currency('USD') }}
{# Output: oh hai #}

# `date`

Formats a timestamp or DateTime (opens new window) object.

{{ entry.postDate|date }}
{# Output: Jan 19, 2038 #}

# Arguments

format

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

{{ now|date('n/d/Y') }}
{# Output: 1/19/2038 #}

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

Format	Example
`short`	1/19/2038
`medium` (default)	Jan 19, 2038
`long`	January 19, 2038
`full`	Tuesday, January 19, 2038

{{ entry.postDate|date('short') }}
{# Output: 1/19/2038 #}

locale

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: 19/1/2038 #}

timezone

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

{{ entry.postDate|date('Y-m-d H:i', timezone='UTC') }}
{# Output: 2038-01-19 03:14 #}

Pass false to prevent the date from being converted to the system’s timezone:

{{ entry.customDateFieldWithTimezone|date('Y-m-d H:i', timezone=false) }}
{# Output: 2038-01-18 19:14 #}

Applying the filter to a null value uses the current date. If this is the desired behavior, consider explicitly passing the now variable: now|date.

# `datetime`

Formats a timestamp or DateTime (opens new window) object, including the time of day.

{{ entry.postDate|datetime }}
{# Output: Jan 19, 2038, 5:00:00 PM #}

# Arguments

format

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

{{ entry.postDate|datetime('short') }}
{# Output: 1/19/2038, 5:00 PM #}

Possible format values (in addition to any valid PHP date format (opens new window)) are:

Format	Example
`short`	1/19/2038, 3:14 AM
`medium` (default)	Jan 19, 2038, 3:14:07 AM
`long`	January 19, 2038 at 3:14:07 AM UTC
`full`	Tuesday, January 19, 2038 at 3:14:07 AM UTC

locale

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: 19/01/2038, 3:14 #}

timezone

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

{{ entry.postDate|datetime('short', timezone='UTC') }}
{# Output: 1/19/2038, 3:14 AM #}

Pass false to prevent the date from being converted to the system’s timezone:

{{ entry.customDateFieldWithTimezone|date('short', timezone=false) }}
{# Output: 1/18/2038, 7:14 PM #}

Applying the filter to a null value uses the current date. If this is the desired behavior, consider explicitly passing the now variable: now|date.

# `diff`

Returns the difference between arrays, using array_diff() (opens new window).

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 (opens new window) object or integer (number of seconds) through craft\helpers\DateTimeHelper::humanDuration() (opens new window) to output human-friendly duration text.

<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 #}

If the passed-in value isn’t a valid number it will be returned verbatim:

{{ 'oh hai'|filesize }}
{# Output: oh hai #}

# `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 (opens new window) filter.

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

# `float`

Coerces the passed value to a float using PHP’s floatval() (opens new window) function. Useful when dealing with stronger typing in PHP 8 and Twig 3.x.

# `group`

Groups items in an array by 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 passing data in plain view (i.e. via front-end forms) that must not be tampered with.

{{ hiddenInput('foo', 'bar'|hash) }}

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

$foo = Craft::$app->getRequest()->getBodyParam('foo');
$foo = Craft::$app->getSecurity()->validateData($foo);

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

Do not hash sensitive data. Hashed values are tamper-proof, but still expose the original value!

Request::getValidatedBodyParam() (opens new window) can also perform this comparison in a controller, automatically throwing an error when it finds a missing or invalid value:

public function actionSubmitData()
{
    $foo = Craft::$app->getRequest()->getValidatedBodyParam('foo');

    // $foo is valid!
}

Hashing data uses your app’s securityKey config setting, by default. If this setting changes between generating and validating a hash, it will fail!

# `httpdate`

Converts a date to the HTTP format, used by RFC 7231 (opens new window)-compliant HTTP headers like Expires.

{% header "Expires: " ~ expiry|httpdate %}
{# Output: Expires: Thu, 08 Apr 2021 13:00:00 GMT #}

# Arguments

timezone

You can use the timezone param to specify the date’s timezone for conversion to GMT:

{% header 'Expires: ' ~ expiry|httpdate('CET') %}
{# Result: Expires: Thu, 08 Apr 2021 21:00:00 GMT #}

Pass false to use the date’s existing timezone as the basis (prior to conversion to GMT).

# `id`

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

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

# `index`

Runs an array through ArrayHelper::index() (opens new window).

{% 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 %}

# `integer`

Coerces the passed value to a integer using PHP’s intval() (opens new window) function. Useful when dealing with stronger typing in PHP 8 and Twig 3.x.

# `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 (opens new window) 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() (opens new window).

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

# `kebab`

Returns a string formatted in “kebab-case”.

That’s a reference to shish kebabs (opens new window) 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 #}

# `length`

Returns the length of a string or array, or a query’s result count.

If used on anything besides a query, Twig’s built-in length (opens new window) filter logic will be used.

# `literal`

Runs a string through craft\helpers\Db::escapeParam() (opens new window) to escape commas and asterisks so they’re are not treated as special characters in query params.

{% set titleParam = craft.app.request.getQueryParam('title') %}
{% set entry = craft.entries()
  .title(titleParam|literal)
  .one() %}

# `markdown` or `md`

Processes a string with Markdown (opens new window).

{% 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 — Choose the “flavor” of Markdown the parser will use. Must be one of:
- 'original' (Default)
- 'gfm'(GitHub-Flavored Markdown (opens new window))
- 'gfm-comment' (GitHub-Flavored Markdown with newlines converted to <br>s)
- 'extra' (Markdown Extra (opens new window))
- 'pre-escape' (Same as 'original' but forces the encode argument to true)
inlineOnly — Determines whether to only parse inline elements, omitting any <p> tags (defaults to false)
encode — Equivalent to pre-processing the input string with Twig’s escape or e filter (opens new window), i.e: {{ content|e|md }}. Only the original and pre-escape flavors are allowed when encoding is enabled.

Do not output user-submitted content with this filter. The resulting markup is “trusted” by the Twig environment (as though it were output with the |raw filter), and can result in XSS vulnerabilities (opens new window).

To protect your site or app, first pass the text through the escape or e filter (opens new window), or set the escape argument to true.

# `merge`

Merges the passed array with another one.

This has the same behavior as Twig’s merge filter (opens new window) which uses PHP’s array_merge() (opens new window) under the hood:

{% set values = [1, 2] %}
{% set values = values|merge(['Lucille', 'Buster']) %}
{# Result: [1, 2, 'Lucille', 'Buster'] #}

It also works on hashes, where merging occurs on the keys. A key that doesn’t already exist is added, and a key that does already exist only has its value overridden:

{% set items = { 'Buster': 'Bluth', 'Lindsay': 'Bluth' } %}
{% set items = items|merge({ 'Tobias': 'Fünke', 'Lindsay': 'Fünke' }) %}
{# Result: { 'Buster': 'Bluth', 'Tobias': 'Fünke', 'Lindsay': 'Fünke' } #}

If you want to make sure specific values are defined by default in an array, like 'Lindsay': 'Bluth' below, reverse the elements in the call:

{% set items = { 'Buster': 'Bluth', 'Lindsay': 'Bluth' } %}
{% set items = { 'Tobias': 'Fünke', 'Lindsay': 'Fünke' }|merge(items) %}
{# Result: { 'Tobias': 'Fünke', 'Lindsay': 'Bluth', 'Buster': 'Bluth' } #}

You can also provide an optional recursive argument that will use ArrayHelper::merge() (opens new window) to merge nested arrays or hashes.

Without recursive:

{% set items = {
  'rebellion': { 'Bespin': 'Calrissian', 'Hoth': 'Organa', 'Crait': 'Organa' },
  'empire': { 'Coruscant': 'Palpatine', 'Endor': 'Palpatine' }
} %}
{% set items = items|merge({
  'rebellion': { 'Endor': 'Solo/Organa' },
  'empire': { 'Bespin': 'Vader', 'Hoth': 'Veers' }
}) %}
{# Result: {
  'rebellion': { 'Endor': 'Solo/Organa' },
  'empire': { 'Bespin': 'Vader', 'Hoth': 'Veers' }
} #}

With recursive:

{% set items = {
  'rebellion': { 'Bespin': 'Calrissian', 'Hoth': 'Organa', 'Crait': 'Organa' },
  'empire': { 'Coruscant': 'Palpatine', 'Endor': 'Palpatine' }
} %}
{% set items = items|merge({
  'rebellion': { 'Endor': 'Solo/Organa' },
  'empire': { 'Bespin': 'Vader', 'Hoth': 'Veers' }
}, true) %}
{# Result: {
  'rebellion': {
    'Bespin': 'Calrissian',
    'Hoth': 'Organa',
    'Crait': 'Organa',
    'Endor': 'Solo/Organa'
  },
  'empire': {
    'Coruscant': 'Palpatine',
    'Endor': 'Palpatine',
    'Bespin': 'Vader',
    'Hoth': 'Veers'
  }
} #}

# `money`

Outputs a value from a Money object.

{{ myMoneyField|money }}
{# Output: $123.00 #}

An optional formatLocale argument can be provided if you don’t want to use the default formatter’s locale:

{{ myMoneyField|money('de') }}
{# Output: 123,00 $ #}

# `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() (opens new window) 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` or `ns`

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

# `namespaceAttributes`

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

It’s identical to the namespace filter, except that inputs’ name attributes won’t be modified.

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|namespaceAttributes('foo') }}

would become this:

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

Notice how the #title CSS selector became #foo-title, the id attribute changed from title to foo-title, but the name attribute wasn’t changed.

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

{{ html|namespaceAttributes('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="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.

For example, comma group symbols are added by default in English:

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

The value is passed to Craft::$app->getFormatter()->asDecimal() (opens new window) and may include three additional arguments:

decimals – number of digits that should appear after the decimal point (defaults to null)
options – key-value array of number formatter options (opens new window) (ignored if PHP intl extension is not installed)
textOptions – key-value array of text formatting options (opens new window) for the formatter

{{ 1000000|number(2) }}
{# Output: 1,000,000.00 #}

{{ 1000000|number(null, { (constant('NumberFormatter::GROUPING_SIZE')): 4 }) }}
{# Output: 100,0000 #}

{{ (-5)|number(null, {}, { (constant('NumberFormatter::NEGATIVE_PREFIX')): '☹' }) }}
{# Output: ☹5 #}

If the passed-in value isn’t a valid number it will be returned verbatim:

{{ 'oh hai'|number }}
{# Output: oh hai #}

# `parseAttr`

Parses an HTML tag to find its attributes.

{% set content %}
  <a class="text-xl pt-0" href="/foo.pdf" download>Save File</p>
{% endset %}

{{ content|parseAttr }}
{# Result: ["class" => ["text-xl", "pt-0"], "href" => "/foo.pdf", "download" => true] #}

# `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.

{{ 0.85|percentage }}
{# Output: 85% #}

If the passed-in value isn’t a valid number it will be returned verbatim:

{{ 'oh hai'|percentage }}
{# Output: oh hai #}

# `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 (opens new window).

{{ user.bio|purify }}

To load predefined rules from a file in config/htmlpurifier/, pass its filename as an argument (without .json):

{{ user.bio|purify('user-profile') }}

Define config on-the-fly by passing an object:

{{ user.bio|purify({
  'HTML.AllowedElements': 'p, a',
  'HTML.Nofollow': true,
}) }}

See the configuration docs for more information on using HTML Purifier.

# `push`

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

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

# `removeClass`

Removes a class (or classes) from the given HTML tag.

{% set markup = '<p class="apple orange banana">A classy bit of text.</p>' %}
{{ markup|removeClass('orange') }}
{# Result: <p class="apple banana">A classy bit of text.</p> #}

{% set markup = '<p class="apple orange banana">A classy bit of text.</p>' %}
{{ markup|removeClass(['orange', 'banana']) }}
{# Result: <p class="apple">A classy bit of text.</p> #}

# `replace`

Match and replace parts of a string.

When a mapping array is passed, this works identically to Twig’s core replace (opens new window) filter:

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

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

To replace one string at a time, pass the string you want to replace as the first argument, and the replacement as the second argument:

{% 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]+/', '-') }}

When passing an array, its keys can be regular expressions:

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

To treat patterns as literal strings (when using positional arguments or a map), pass false to the regex argument:

{{ tag.title|lower|replace({
  '/you/i': 'y’all',
  '/-_-/': '(^_^)',
}, regex=false) }}

# `rss`

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

{{ entry.postDate|rss }}
{# Expires: Wed, 31 May 2023 12:23:09 -0700 #}

# Arguments

timezone

You can use the timezone param to specify the date’s timezone for conversion to GMT:

{% header 'Expires: ' ~ expiry|httpdate('CET') %}
{# Expires: Thu, 08 Apr 2021 21:00:00 +0000 #}

Pass false to use the date’s existing timezone as the basis (prior to conversion to GMT).

# `snake`

Returns a string formatted in “snake_case”.

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

# `string`

Coerces the passed value to a string using PHP’s strval() (opens new window) function. Useful when dealing with stronger typing in PHP 8 and Twig 3.x.

# `time`

Outputs the time of day for a timestamp or DateTime (opens new window) object.

{{ entry.postDate|time }}
{# Output: 3:14:07 AM #}

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

{{ entry.postDate|time('short') }}
{# Output: 3:14 AM #}

Possible format values are:

Format	Example
`short`	3:14 AM
`medium` (default)	3:14:07 AM
`long`	3:14:07 AM UTC

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`

Outputs a date with craft\i18n\Formatter::asTimestamp() (opens new window), using plain-language relative terms when possible. Dates with the same day return only the time, using the provided format; dates from the previous 24-hour window return yesterday; dates within the last week return the day’s name (like Wednesday). Anything longer ago than that

{{ now|timestamp }}
{# Output: 16:25 #}

{{ now|date_modify('-1 day')|timestamp }}
{# Output: Yesterday #}

{{ now|date_modify('-4 days')|timestamp }}
{# Output: Friday #}

{{ now|date_modify('-2 months')|timestamp(withPreposition=true) }}
{# Output: 'on March 29, 2023' #}

# Arguments

withPreposition: Pass true to include at or on prepositions when outputting the timestamp (when appropriate). These values are localized based on the current site’s language. Defaults to false.

# `translate` or `t`

Translates a message with Craft::t() (opens new window).

{{ '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`

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() (opens new window).

{% 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 = array1|unshift('bar', 'baz') %}
{# Result: ['bar', 'baz', 'foo'] #}

# `ucwords`

Uppercases the first character of each word in a string.

{{ 'foo bar baz hyphenated-pair'|ucwords }}
{# Output: Foo Bar Baz Hyphenated-Pair #}

# `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() (opens new window).

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

# `widont`

Inserts a non-breaking space between the last two words of a string.

This can be useful to prevent typographic widows and orphans (opens new window).

{% set content %}
  Don’t leave any word stranded on its own line.
{% endset %}

{{ content|widont }}
{# Output: Don’t leave any word stranded on its own&nbsp;line. #}

# `without`

Returns an array without the specified item(s).

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

# `withoutKey`

Returns an array without one or more specified keys.

The key can be a single key as a string:

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

You can also pass multiple keys in an array:

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

Filters

# address

# append

# ascii

# atom

# attr

# base64_decode

# base64_encode

# boolean

# camel

# column

# contains

# currency

# date

# Arguments

# datetime

# Arguments

# diff

# duration

# encenc

# explodeClass

# explodeStyle

# filesize

# filter

# float

# group

# hash

# httpdate

# Arguments

# id

# index

# indexOf

# integer

# intersect

# json_encode

# json_decode

# kebab

# lcfirst

# length

# literal

# markdown or md

# merge

# money

# multisort

# namespace or ns

# namespaceAttributes

# namespaceInputId

# namespaceInputName

# number

# parseAttr

# parseRefs

# pascal

# percentage

# prepend

# purify

# push

# removeClass

# replace

# rss

# Arguments

# snake

# string

# time

# timestamp

# Arguments

# translate or t

# truncate

# ucfirst

# unique

# unshift

# ucwords

# values

# where

# widont

# without

# withoutKey

Was this page helpful?

# `address`

# `append`

# `ascii`

# `atom`

# `attr`

# `base64_decode`

# `base64_encode`

# `boolean`

# `camel`

# `column`

# `contains`

# `currency`

# `date`

# `datetime`

# `diff`

# `duration`

# `encenc`

# `explodeClass`

# `explodeStyle`

# `filesize`

# `filter`

# `float`

# `group`

# `hash`

# `httpdate`

# `id`

# `index`

# `indexOf`

# `integer`

# `intersect`

# `json_encode`

# `json_decode`

# `kebab`

# `lcfirst`

# `length`

# `literal`

# `markdown` or `md`

# `merge`

# `money`

# `multisort`

# `namespace` or `ns`

# `namespaceAttributes`

# `namespaceInputId`

# `namespaceInputName`

# `number`

# `parseAttr`

# `parseRefs`

# `pascal`

# `percentage`

# `prepend`

# `purify`

# `push`

# `removeClass`

# `replace`

# `rss`

# `snake`

# `string`

# `time`

# `timestamp`

# `translate` or `t`

# `truncate`

# `ucfirst`

# `unique`

# `unshift`

# `ucwords`

# `values`

# `where`

# `widont`

# `without`

# `withoutKey`