Filters

Contents

Eleventy Provided Filters
- Access existing filters in your Configuration File
Asynchronous Filters
Scoped Data in Filters
Per-Engine filters
From the Community

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:

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

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

Scoped Data in Filters

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

this.page Added in v2.0.0
this.eleventy Added in v2.0.0

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

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) { … });
};