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 11ty.cjs

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

ESM CommonJS

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

ESM CommonJS

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

ESM CommonJS

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

ESM CommonJS

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

ESM CommonJS

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