Filters Jump to heading
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:
<h1>{{ name | makeUppercase }}</h1><h1>{{ name | makeUppercase }}</h1>module.exports = function({name}) {
return `<h1>${this.makeUppercase(name)}</h1>`;
};<h1>{{ makeUppercase name }}</h1>These can be added using the Configuration API. Here are a few examples:
module.exports = function(eleventyConfig) {
// Liquid Filter
eleventyConfig.addLiquidFilter("makeUppercase", function(value) { … });
// Nunjucks Filter
eleventyConfig.addNunjucksFilter("makeUppercase", function(value) { … });
// Handlebars Filter
eleventyConfig.addHandlebarsHelper("makeUppercase", function(value) { … });
// JavaScript Template Function
eleventyConfig.addJavaScriptFunction("makeUppercase", function(value) { … });
// or, use a Universal filter (an alias for all of the above)
eleventyConfig.addFilter("makeUppercase", function(value) { … });
// New in v2.0.0
eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { … });
};Read more about filters on the individual Template Language documentation pages:
Universal Filters Jump to heading
Universal filters can be added in a single place and are available to multiple template engines, simultaneously. This is currently supported in JavaScript, Nunjucks, Liquid, Handlebars, and WebC.
module.exports = function(eleventyConfig) {
// Universal filters add to:
// * Liquid
// * Nunjucks
// * Handlebars
// * JavaScript
eleventyConfig.addFilter("myFilter", function(value) {
return value;
});
};Eleventy Provided Universal Filters Jump to heading
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.loginside templates.get*CollectionItem: Get next or previous collection items for easy linking.
Access existing filters Added in v0.11.0 Jump to heading
If you’d like to reuse existing filters in a different way, consider using the new Configuration API getFilter method. You can use this to alias a filter to a different name. You can use this to use a filter inside of your own filter. You can use this to use 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 Universal 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.
If you are not yet on Eleventy 2.0, you can still add asynchronous filters to each async-friendly template language individually: Liquid addLiquidFilter, Nunjucks addNunjucksAsyncFilter, and JavaScript addJavaScriptFunction.
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 Jump to heading
A few Eleventy-specific data properties are available to filter callbacks.
this.pageAdded in v2.0.0this.eleventyAdded in v2.0.0
module.exports = function(eleventyConfig) {
// Make sure you’re not using an arrow function here: () => {}
eleventyConfig.addFilter("myFilter", function() {
// this.page
// this.eleventy
});
};