Daniele Cammarata

Understanding Nunjucks Filters

At its core, Nunjucks filters are functions that modify the output of template variables. They allow you to manipulate data directly within your templates, providing a convenient way to format, transform, or customize content on the fly. Whether you’re dealing with strings, numbers, arrays, or objects, Nunjucks filters offer a flexible mechanism to tailor your data according to your requirements.

Syntax and Usage

Using Nunjucks filters is straightforward. They are invoked within your templates using the pipe character (|) followed by the filter name, like so:

{{ variable | filterName }}

You can also chain multiple filters together for more complex transformations:

{{ variable | filter1 | filter2 | ... }}

Built-in Filters

Nunjucks comes with a variety of built-in filters that cover common use cases. Some of the most frequently used ones include:

upper and lower: Convert text to uppercase or lowercase.
capitalize: Capitalize the first letter of a string.
default: Set a default value if a variable is not defined or is falsy.
join: Join elements of an array into a string using a specified separator.
slice: Extract a portion of a string or array.
reverse: Reverse the order of elements in an array.

These are just a few examples, and Nunjucks provides many more filters out of the box, each serving a specific purpose.

Custom Filters

One of the most powerful aspects of Nunjucks filters is the ability to create custom filters tailored to your project’s needs. You can define custom filters by registering them with the Nunjucks environment:

const nunjucks = require('nunjucks');

const env = nunjucks.configure();

env.addFilter('customFilter', (input, arg1, arg2) => {
    // Custom filter logic
});

Once registered, you can use your custom filter in templates just like any built-in filter:

{{ variable | customFilter(arg1, arg2) }}

Practical Examples

Let’s walk through a few practical examples to demonstrate the power of Nunjucks filters:

Date Formatting: Suppose you have a date object and want to display it in a specific format. You can create a custom filter to handle the formatting:

env.addFilter('dateFormat', (date, format) => {
    // Custom date formatting logic
});

In your template:

{{ myDate | dateFormat('YYYY-MM-DD') }}

Currency Formatting: You can create a custom filter to format numbers as currency:

env.addFilter('currencyFormat', (number, currency) => {
    // Custom currency formatting logic
});