Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Stable
2.0.1
Toggle Menu
Eleventy 1.93s
Gatsby 29.05s

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:

Filename sample.njk
<h1>{{ name | makeUppercase }}</h1>
Filename sample.liquid
<h1>{{ name | makeUppercase }}</h1>
Filename sample.11ty.js
export default function({name}) {
return `<h1>${this.makeUppercase(name)}</h1>`;
};
Filename sample.11ty.cjs
module.exports = function({name}) {
return `<h1>${this.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, and WebC.

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.addFilter("makeUppercase", function(value) { /* … */ });

eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { /* … */ });
};
module.exports = function (eleventyConfig) {
eleventyConfig.addFilter("makeUppercase", function(value) { /* … */ });

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

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

  • url: Normalize absolute paths in your content, allows easily changing deploy subdirectories for your project.
  • slugify: "My string" to "my-string" for permalinks.
  • log: console.log inside templates.
  • get*CollectionItem: Get next or previous collection items for easy linking.
  • inputPathToUrl: Map a template’s input path to its output URL.
  • renderTransforms: Render project transforms on an arbitrary block of content.

Access existing filters in your Configuration File

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.

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.addShortcode("myCustomImage", function (url, alt) {
return `<img src="${eleventyConfig.getFilter("url")(url)}" alt="${alt}">`;
});
};
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

Eleventy has added a new universal filter API for asynchronous filters and extended the currently available addFilter method to be async-friendly.

eleventy.config.js
export default 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;
});
};
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;
});
};

Scoped Data in Filters

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

  • this.page Added in v2.0.0 (Learn about page)
  • this.eleventy Added in v2.0.0 (Learn about eleventy)
  • this.env (Nunjucks-specific) Added in v3.0.0
  • this.ctx (Nunjucks-specific) Added in v3.0.0
eleventy.config.js
export default function (eleventyConfig) {
// Make sure you’re not using an arrow function here: () => {}
eleventyConfig.addFilter("myFilter", function () {
// this.page
// this.eleventy
});
};
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

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.)

eleventy.config.js
export default 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() { /* … */ });

// JavaScript Template Function (async-friendly)
eleventyConfig.addJavaScriptFunction("myFilter", async function(value) { /* … */ });
};
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() { /* … */ });

// 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.

From the Community

Γ—69 resources courtesy of 11tybundle.dev curated by IndieWeb Avatar for https://www.bobmonsour.com/Bob Monsour

Expand to see 64 more resources.

Other pages in Configuration: