Filters

A filter transforms a value: {{= value | name }} or {{= value | name(argument, ...) }}. Filters chain from left to right, and each applies to the single operand before it, so use parentheses to filter a whole expression: {{= (a + b) | fixed }}. The specification has the details.

The language has no array or object literals, so the examples that need one show the data they are rendered with. Where a result is not a string, it is passed through json to make it visible. Every example on this page is run by the test suite.

String Filters

capitalize

Capitalizes the first letter of each word.

{{= "hello world" | capitalize }}

Output: Hello World

lower

Converts a string to lowercase.

{{= "HELLO WORLD" | lower }}

Output: hello world

upper

Converts a string to uppercase.

{{= "hello world" | upper }}

Output: HELLO WORLD

trim

Removes whitespace from both ends of a string.

[{{= "  hello world  " | trim }}]

Output: [hello world]

truncate

Shortens a string to at most maxLength characters, ending it with ... (or the string given as second argument).

{{= "This is a very long string" | truncate(10) }}

Output: This is a ...

{{= "This is a very long string" | truncate(10, "…") }}

Output: This is a …

replace

Replaces every match of a pattern. The pattern is a regular expression.

{{= "hello world" | replace("world", "there") }}

Output: hello there

{{= "a1b22c" | replace("\d+", "-") }}

Output: a-b-c

repeat

Repeats a string.

{{= "ab" | repeat(3) }}

Output: ababab

split

Splits a string into an array.

{{= "1,2,3" | split(",") | json }}

Output: ["1","2","3"]

slugify

Converts a string to a URL-friendly slug.

{{= "Hello World! This is a Test" | slugify }}

Output: hello-world-this-is-a-test

wordCount

Counts the words in a string.

{{= "Hello world from Janja" | wordCount }}

Output: 4

stripTags

Removes HTML tags from a string.

{{= html | stripTags }}

Data: { "html": "<p>Hello <strong>world</strong></p>" }

Output: Hello world

urlencode

Encodes a string for use in a URL.

{{= "tom & jerry" | urlencode }}

Output: tom%20%26%20jerry

urldecode

Decodes a URL-encoded string.

{{= "hello%20world" | urldecode }}

Output: hello world

Number Filters

abs

Returns the absolute value.

{{= -5 | abs }}

Output: 5

ceil

Rounds up to the nearest integer.

{{= 4.2 | ceil }}

Output: 5

round

Rounds to a number of decimal places (default 0).

{{= 4.567 | round(2) }}

Output: 4.57

{{= 4.567 | round }}

Output: 5

fixed

Formats with a fixed number of decimal places (default 2).

{{= 4.5 | fixed }}

Output: 4.50

{{= 4.5678 | fixed(1) }}

Output: 4.6

percent

Formats a fraction as a percentage.

{{= 0.75 | percent }}

Output: 75%

{{= 0.1234 | percent(1) }}

Output: 12.3%

currency

Formats a number as currency. Arguments: the currency code (default "USD") and the locale (default "en-US").

{{= 1234.56 | currency }}

Output: $1,234.56

{{= 1234.56 | currency("EUR") }}

Output: €1,234.56

add

Adds a number.

{{= 5 | add(3) }}

Output: 8

sub

Subtracts a number.

{{= 5 | sub(3) }}

Output: 2

mul

Multiplies by a number.

{{= 5 | mul(3) }}

Output: 15

div

Divides by a number.

{{= 6 | div(3) }}

Output: 2

max

Returns the largest of the value and the arguments.

{{= 5 | max(3, 8, 2) }}

Output: 8

min

Returns the smallest of the value and the arguments.

{{= 5 | min(3, 8, 2) }}

Output: 2

sum

Adds up an array of numbers.

{{= numbers | sum }}

Data: { "numbers": [1, 2, 3, 4, 5] }

Output: 15

even

Tests whether a number is even.

{{= 4 | even }}

Output: true

odd

Tests whether a number is odd.

{{= 3 | odd }}

Output: true

Array Filters

length

Returns the length of an array or a string.

{{= items | length }}

Data: { "items": [1, 2, 3] }

Output: 3

{{= "hello" | length }}

Output: 5

first

Returns the first element of an array, or the first character of a string.

{{= items | first }}

Data: { "items": [1, 2, 3] }

Output: 1

last

Returns the last element of an array, or the last character of a string.

{{= items | last }}

Data: { "items": [1, 2, 3] }

Output: 3

join

Joins the elements with a separator (default: none).

{{= items | join(", ") }}

Data: { "items": [1, 2, 3] }

Output: 1, 2, 3

reverse

Returns a reversed copy of an array or a string.

{{= items | reverse | json }}

Data: { "items": [1, 2, 3] }

Output: [3,2,1]

{{= "abc" | reverse }}

Output: cba

sort

Returns a sorted copy of an array or a string. Elements are compared as strings, like JavaScript's Array.prototype.sort() without a comparator.

{{= items | sort | json }}

Data: { "items": ["pear", "apple", "fig"] }

Output: ["apple","fig","pear"]

unique

Removes duplicates from an array or a string.

{{= items | unique | json }}

Data: { "items": [1, 2, 2, 3, 1] }

Output: [1,2,3]

compact

Removes null and undefined elements.

{{= items | compact | json }}

Data: { "items": [1, null, 2, null, 3] }

Output: [1,2,3]

slice

Returns the part of an array or a string from start up to, but not including, end.

{{= items | slice(1, 4) | json }}

Data: { "items": [1, 2, 3, 4, 5] }

Output: [2,3,4]

{{= "hello" | slice(1) }}

Output: ello

chunk

Splits an array into arrays of a given size.

{{= items | chunk(2) | json }}

Data: { "items": [1, 2, 3, 4, 5] }

Output: [[1,2],[3,4],[5]]

shuffle

Returns a copy of an array in random order.

{{= items | shuffle | json }}

Data: { "items": [1, 2, 3, 4, 5] }

pluck

Reads one property of every element.

{{= people | pluck("name") | json }}

Data: { "people": [{ "name": "Alice", "team": "core" }, { "name": "Bob", "team": "docs" }, { "name": "Carol", "team": "core" }] }

Output: ["Alice","Bob","Carol"]

map

Like pluck, with an optional default for elements that lack the property.

{{= people | map("nickname", "n/a") | json }}

Data: { "people": [{ "name": "Alice", "nickname": "Al" }, { "name": "Bob" }] }

Output: ["Al","n/a"]

groupby

Groups the elements of an array by the value of a property.

{{= people | groupby("team") | json }}

Data: { "people": [{ "name": "Alice", "team": "core" }, { "name": "Bob", "team": "docs" }, { "name": "Carol", "team": "core" }] }

Output: {"core":[{"name":"Alice","team":"core"},{"name":"Carol","team":"core"}],"docs":[{"name":"Bob","team":"docs"}]}

Object Filters

keys

Returns the keys of an object. Use it to loop over an object: {{ for key of user | keys }}.

{{= user | keys | json }}

Data: { "user": { "name": "Alice", "age": 30, "city": "NYC" } }

Output: ["name","age","city"]

values

Returns the values of an object.

{{= user | values | json }}

Data: { "user": { "name": "Alice", "age": 30, "city": "NYC" } }

Output: ["Alice",30,"NYC"]

entries

Returns the key-value pairs of an object.

{{= user | entries | json }}

Data: { "user": { "name": "Alice", "age": 30, "city": "NYC" } }

Output: [["name","Alice"],["age",30],["city","NYC"]]

get

Reads a nested value by its path, without failing when a part of the path is missing.

{{= account | get("owner", "name") }}

Data: { "account": { "owner": { "name": "Alice" } } }

Output: Alice

[{{= account | get("billing", "city") }}]

Data: { "account": { "owner": { "name": "Alice" } } }

Output: []

pick

Returns an object with only the given keys.

{{= user | pick("name", "age") | json }}

Data: { "user": { "name": "Alice", "age": 30, "city": "NYC" } }

Output: {"name":"Alice","age":30}

omit

Returns an object without the given keys.

{{= user | omit("age") | json }}

Data: { "user": { "name": "Alice", "age": 30, "city": "NYC" } }

Output: {"name":"Alice","city":"NYC"}

defaults

Fills in the keys an object does not have.

{{= user | defaults(fallbacks) | json }}

Data: { "user": { "name": "Alice" }, "fallbacks": { "age": 0, "city": "Unknown" } }

Output: {"age":0,"city":"Unknown","name":"Alice"}

merge

Merges objects; later ones win.

{{= a | merge(b, c) | json }}

Data: { "a": { "x": 1 }, "b": { "y": 2 }, "c": { "x": 3 } }

Output: {"x":3,"y":2}

invert

Swaps keys and values.

{{= codes | invert | json }}

Data: { "codes": { "ok": 200, "missing": 404 } }

Output: {"200":"ok","404":"missing"}

Date Filters

date

Formats a Date, or a string that JavaScript can parse as a date. An invalid date gives an empty string.

Format	Result
"ISO" (default)	ISO 8601
"date"	YYYY-MM-DD
"time"	HH:MM:SS, in the time zone of the machine that renders
"locale", "locale-time", "locale-datetime"	Formatted for the locale of the machine that renders

{{= published | date }}

Data: { "published": "2024-01-15T10:30:00.000Z" }

Output: 2024-01-15T10:30:00.000Z

{{= published | date("date") }}

Data: { "published": "2024-01-15T10:30:00.000Z" }

Output: 2024-01-15

timeAgo

Describes how long ago a date was: just now, 5 minutes ago, 2 hours ago, 3 days ago, ...

{{= published | timeAgo }}

Data: { "published": "2024-01-15T10:30:00.000Z" }

Utility Filters

safe

Marks a string as trusted HTML, so it is written without escaping. Only use it for content you control: see Security.

{{= html }}

Data: { "html": "<b>bold</b>" }

Output: <b>bold</b>

{{= html | safe }}

Data: { "html": "<b>bold</b>" }

Output: <b>bold</b>

json

Serializes a value as JSON, optionally indented. The result is not escaped.

{{= user | json }}

Data: { "user": { "name": "Alice", "tags": ["a", "b"] } }

Output: {"name":"Alice","tags":["a","b"]}

fallback

Replaces null and undefined with a default. Pass true as second argument to replace every falsy value, such as "" and 0.

{{= nickname | fallback("Anonymous") }}

Output: Anonymous

[{{= "" | fallback("Anonymous") }}]

Output: []

{{= "" | fallback("Anonymous", true) }}

Output: Anonymous

Async Filters

fetchUrl

Fetches a URL and returns the response body as text. The template waits for it.

{{= "https://api.example.com/motd" | fetchUrl }}

delay

Returns the value after a number of milliseconds.

{{= "hello" | delay(1000) }}

Chaining Filters

{{= "  HELLO WORLD  " | trim | lower | capitalize }}

Output: Hello World

{{= items | slice(1, 4) | reverse | join(" - ") }}

Data: { "items": [1, 2, 3, 4, 5] }

Output: 4 - 3 - 2

Custom Filters

A filter is a function that receives the value followed by the arguments. Register filters with the filters option; they are added to the built-in ones, and may be async:

import { Renderer } from 'janja';

const renderer = new Renderer({
  filters: {
    shout: (value: string, times = 1) => value.toUpperCase() + '!'.repeat(times),
  },
});

await renderer.render('{{= "hello" | shout(3) }}', {});
// "HELLO!!!"

Using a filter that is not registered is an error when the expression is evaluated; validateTemplate() and janja check report it beforehand.

Coming from Jinja2

Most Jinja2 filters exist under the same name. These differ:

Jinja2	Janja
title	capitalize
striptags	stripTags
wordcount	wordCount
default	fallback
tojson	json
escape	not needed: output is escaped by default
value | truncate(10)	the same; arguments always go in parentheses