Aug 15, 2022

11ty Second 11ty: Creating Template Filters

11ty Template filters are ways of manipulating data in a variable tag in your template language of choice. Each template language brings it’s own set and 11ty adds a few defaults, as well.

Using a built-in filter

To use a built-in filter, write a variable or expression in your language of choice, here’s a liquid template that will display the string “hi there” on the page.

<body>
    <h1>11ty Second 11ty: Filter Example</h1>
    <h2>{{ "hi there" }}</h2>
</body>

Once you have that, add the pipe character and the filter’s name. In this case, the built-in slugify filter will convert the string to a url-appropriate string.

<body>
    <h1>11ty Second 11ty: Filter Example</h1>
    <h2>{{ "hi there" | slugify }}</h2>
</body>

<!-- Outputs: <h2>hi-there</h2>

Making custom filters

Next to make a custom filter, we need to have a configuration file. We’ll create .eleventy.js in our project root.

From there, we’ll export out a function that has the eleventyConfig object and use the addFilter method on that object.

The method takes two properties, a name for the filter for use in the template, and a function that will be used to mutate the data.

In this case, we’ll make an uppercase filter to convert our string to all uppercase. The function we’ll make takes the first argument of the string the filter is applied to. In this case, we’ll use string.toUpperCase() in Javascript to return the mutated string.

module.exports = function(eleventyConfig) {
  eleventyConfig.addFilter("uppercase", function(string) {
    return string.toUpperCase();
  })
}

Then we can use this in the template:

 <h1>11ty Second 11ty: Filter Example</h1>
 <h2>{{ "hi there" | uppercase }}</h2>

You can also adjust markup around your string, as well. In this case, we’ll take the bad idea of adjusting the string’s color in our filter. Any argument after the first in our filter will be the options that can be passed to the filter. In this case a color string. We can wrap the string in a span and set the color inline.

module.exports = function(eleventyConfig) {
  eleventyConfig.addFilter("uppercase", function(string) {
    return string.toUpperCase();
  })

  eleventyConfig.addFilter("color", function(string, color) {
    return `<span style="color: ${color}">${string}</span>`;
  })
}

Then we can use this in the template:

 <h1>11ty Second 11ty: Filter Example</h1>
 <h2>{{ "hi there" | color: "red" }}</h2>

And more!

Filters can be a super powerful piece of your 11ty builds. They allow you to mutate data on the fly no matter the source. Anything you can do in Javascript, you can do in a filter, so play around with things like creating a date string filter for Nunjucks (only available in Liquid) or reordering array or creating a strong set of HTML templates for common use cases in your markup or markdown.