Creating a custom Eleventy filter

— 6 minute read

Alright, I wanted to make this article a bit bigger but hit a roadblock when trying to use filters in Eleventy.

So I decided to dedicate this article to showcasing how filters can work in Eleventy.

A filter is basically a function we can extend in our frontend by calling the pipe | delimiter followed by the function.

{
  {
    someVar | uppercase;
  }
}

The uppercase is then counted as our filter.

Eleventy Filter types

Eleventy actually knows quite a few filter types, as mentioned on their documentation on Filters

module.exports = function(eleventyConfig) {
  // Liquid Filter
  eleventyConfig.addLiquidFilter("uppercase", function(value) { … });

  // Nunjucks Filter
  eleventyConfig.addNunjucksFilter("uppercase", function(value) { … });

  // Handlebars Filter
  eleventyConfig.addHandlebarsHelper("uppercase", function(value) { … });

  // JavaScript Template Function
  eleventyConfig.addJavaScriptFunction("uppercase", function(value) { … });

  // or, use a Universal filter (an alias for all of the above)
  eleventyConfig.addFilter("uppercase", function(value) { … });
};

We are going to use the Universal filter method.

What I kind of missed in the documentation was the ability to add parameters to the function.

Adding arguments to the filter

So far we have been talking about an uppercase filter, but we actually want to make a filteredPosts one.

What it should do:

Filter posts and slice the first {x} from the results

You might wonder why?

Because my layout uses three separate layouts it made more sense to split them out.

{% set firstItem = pagination.items[0] %}
{% set secondItem = pagination.items[1] %}
{% set postListItems = pagination.items | filteredPosts(2) %}

Here you can see how I set my variables.

You might have spotted the filter already! And more importantly how the argument is passed to it.

filteredPosts(argument)

Building the filtered post filter

To build this filter we need to modify our .eleventy.js file.

config.addFilter('filteredPosts', function(value, argument) {
  return modifiedValue;
});

This is our universal filter that accepts the argument. It always receives the value, but the second part is the argument.

We want to strip out the first 2 elements, for which we can use the slice method.

I had some issues when using slice vs splice, but a quick refresh on those made me realise we can use splice to modify the incoming value, remove the first 2 elements and return it.

config.addFilter('filteredPosts', function(value, limit) {
  value.splice(0, limit);
  return value;
});

That makes sure the first two elements are cut from the array since we already assigned them to their own variables.

Adding multiple arguments

We can of course, also send multiple arguments to our Eleventy Filter.

{% set postListItems = collections.posts | filteredPosts(0, 2) %}

And receive them as such:

config.addFilter('filteredPosts', function(value, from, limit) {
  value.splice(from, limit);
  return value;
});

We could even set default values:

config.addFilter('filteredPosts', function(value, from = 0, limit = 2) {
  value.splice(from, limit);
  return value;
});

There you go, I hope this helps someone creating their own cool filters with Eleventy 🤩.

Thank you for reading, and let's connect!

Thank you for reading my blog. Feel free to subscribe to my email newsletter and connect on Facebook or Twitter