The Trevor Project — Saving Young LGBTQ Lives
Eleventy
The possum is Eleventy’s mascot
Eleventy Documentation
Menu
Compare npm install
Eleventy 5.81s
Remix 40.14s

Filters

Contents

A filter is a function which can be used within templating syntax to transform data into a more presentable format. Filters are typically designed to be chained, so that the value returned from one filter is piped into the next filter.

Various template engines can be extended with custom filters to modify content. Here are a few examples:

View this example in: Liquid Nunjucks 11ty.js Handlebars
Filename sample.njk
<h1>{{ name | makeUppercase }}</h1>
Filename sample.liquid
<h1>{{ name | makeUppercase }}</h1>
Filename sample.11ty.js
module.exports = function({name}) {
  return `<h1>${this.makeUppercase(name)}</h1>`;
};
Filename sample.hbs
<h1>{{ makeUppercase name }}</h1>

Filters can be added using the Configuration API and are available to multiple template engines, simultaneously. They are currently supported in JavaScript , Markdown, Nunjucks, Liquid, Handlebars, and WebC.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  eleventyConfig.addFilter("makeUppercase", function(value) { … });

  // New in v2.0.0-beta.1
  eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { … });
};
INFO:
Markdown files are pre-processed as Liquid templates by default—any filters available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the filters available for that templating language will also be available in Markdown files.

Read more about filters on the individual Template Language documentation pages:

Eleventy Provided Filters Jump to heading

We also provide a few universal filters, built-in:

Access existing filters in your Configuration File Jump to heading

If you’d like to reuse existing filters, you can use the Configuration API’s getFilter method. When called with a valid filter name, it will return that filter’s callback function. It can be helpful when aliasing a filter to a different name, using a filter inside of your own filter, or using a filter inside of a shortcode.

module.exports = function(eleventyConfig) {
  eleventyConfig.addShortcode("myCustomImage", function(url, alt) {
    return `<img src="${eleventyConfig.getFilter("url")(url)}" alt="${alt}">`;
  });
};

Asynchronous Filters Added in v2.0.0 Jump to heading

Eleventy has added a new universal filter API for asynchronous filters and extended the currently available addFilter method to be async-friendly. Note that even though Handlebars is used for synchronous filters in addFilter, it is excluded from asynchronous filters because Handlebars is not async-friendly.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Async universal filters add to:
  // * Liquid
  // * Nunjucks
  // * JavaScript

  eleventyConfig.addFilter("myFilter", async function(value) {
    // do some Async work
    return value;
  });

  eleventyConfig.addAsyncFilter("myFilter", async function(value) {
    // do some Async work
    return value;
  });
};
Play Video: Universal Asynchronous Filters (Nunjucks improvement) (Changelog №17) Universal Asynchronous Filters (Nunjucks improvement) (Changelog №17) ▶12m54s

Scoped Data in Filters Jump to heading

A few Eleventy-specific data properties are available to filter callbacks.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Make sure you’re not using an arrow function here: () => {}
  eleventyConfig.addFilter("myFilter", function() {
    // this.page
    // this.eleventy
  });
};

Per-Engine filters Jump to heading

Filters can also be specified individually for one or more template engines. (The addFilter function is actually an alias for calling all of these functions.)

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Liquid Filter (async-friendly)
  eleventyConfig.addLiquidFilter("myFilter", async function(value) { … });

  // Nunjucks Filter
  eleventyConfig.addNunjucksFilter("myFilter", function(value) { … });

  // Nunjucks Async Filter
  // Read the Nunjucks docs before using this (link below)
  eleventyConfig.addNunjucksAsyncFilter("myFilter", function() { … });

  // Handlebars Filter (no async support)
  eleventyConfig.addHandlebarsHelper("myFilter", function(value) { … });

  // JavaScript Template Function (async-friendly)
  eleventyConfig.addJavaScriptFunction("myFilter", async function(value) { … });
};

Note that Nunjucks addNunjucksAsyncFilter requires the use of callbacks for async behavior. Make sure you read up on it!

INFO:
Markdown files are pre-processed as Liquid templates by default—any filters available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the filters available for that templating language will also be available in Markdown files.

Other pages in Configuration:

Related Docs