Filter an Eleventy Collection Using Your Own Custom Front Matter

If you've worked with Eleventy before, you'll likely have been in the situation where you want to filter the output of a collection to only return certain results.

Eleventy has a number ways to output collection items by tag, but often you'll want to group and output items based on other data that you've added to your document's front matter.

So how do you selectively output items that match the value of one of your custom front matter keys? I'll show you how you can create an Eleventy filter to do the job.

See how I do it #

On this website I have a collection called collections.projects and on certain pages I list only Open Source projects i.e. those that include the type: Open Source key in the project front matter.

Here's an example of a project Markdown file with some basic YAML front matter:

---
title: My Cool Open Source Project
date: 2022-10-19
type: Open Source
---
This is my cool open source project content...

By using a custom Universal Filter, I can loop over the collections.projects collection in my Nunjucks template, extracting only the projects that include the type: Open Source key.

Let's go through the steps of installing and using the filter.

Installation #

First install lodash in your Eleventy project so that we can use the deburr method inside the filter to sanitize the key value.

npm install lodash

Next, inside the Eleventy configuration file (typically called eleventy.js) add the line to require lodash at the top of the file:

const lodash = require("lodash");

Next, add the filter inside the module.exports block as shown here:

const lodash = require("lodash");

module.exports = function(eleventyConfig) {

  eleventyConfig.addFilter("include", (arr, path, value) => {

    value = lodash.deburr(value).toLowerCase();
    
    return arr.filter((item) => {
      let pathValue = lodash.get(item, path);
      pathValue = lodash.deburr(pathValue).toLowerCase();
      return pathValue.includes(value);
    });

  });
  
};

Usage in templates #

Here is an example of how you can use the new filter in your templates:

// Apply the include filter to a collection and store the result
{% set openSourceProjects = collections.project | include("data.type", "Open Source") %}

// We can now loop over the stored result e.g. projects with a "type" of "Open Source"
{% for project in openSourceProjects %}

  <h2>{{ project.title }}</h2>
  
{% endfor %}

The above {% for %} loop will only output "Open Source" projects. Voila!

Note: Universal Filters will work with any of Eleventy's supported template engines e.g. Nunjucks, Liquid, JavaScript, Handlebars etc.

Notes #

The filter uses the lodash.deburr method to sanitize the key value you pass into the filter. This will strip any diacriticals from the string leaving basic Latin letters, making it more reliable to work with e.g. when searching an array for a string using the JavaScript .includes() method.

Further reading #

Be sure to look at the Eleventy Documentation to learn more about creating and filtering collections.

Stephanie Eckles over at the excellent 11ty Rocks! has documented a number of useful ways to modify or limit the results from Eleventy collections, and in fact any type of data array in Eleventy. It's a great resource and I recommend you check it out!

Wrapping up #

Hopefully this post has shown you how you can use Universal Filters to filter collection output, and given you a new tool to use in your Eleventy projects.

If you liked this post or if you have anything to add, please reach out to me on Twitter or send me an email.