- Stable
3.0.0
Toggle Menu
1.93s
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:
<h1>{{ name | makeUppercase }}</h1>
<h1>{{ name | makeUppercase }}</h1>
export default function({name}) {
return `<h1>${this.makeUppercase(name)}</h1>`;
};
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.
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) { /* … */ });
};
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.
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.
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 aboutpage
)this.eleventy
Added in v2.0.0 (Learn abouteleventy
)this.env
(Nunjucks-specific) Added in v3.0.0this.ctx
(Nunjucks-specific) Added in v3.0.0
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.)
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!
From the Community
×69 resources courtesy of 11tybundle.dev curated by Bob Monsour
Expand to see 64 more resources.
Other pages in Configuration:
- Configuration Shapes
- Passthrough File Copy
- Ignore Files
- Filters
- 快捷码(Shortcodes)
- Preprocessors
- Custom Tags
- Events
- Transforms
- Watch and Serve
- Memoize