Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
11ty is joining Font AwesomeIndieWeb Avatar for https://fontawesome.com/
Versions
Stable
3.0.0
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Collections API

Contents

To get fancier with your collections (and even do a bit of your own custom filtering, if you’d like), you can use our Configuration API.

Inside of your eleventy.config.js config file, you can use the addCollection method:

eleventy.config.js
export default function (eleventyConfig) {
	// async-friendly
	eleventyConfig.addCollection("myCollectionName", async (collectionsApi) => {
		// get unsorted items
		return collectionsApi.getAll();
	});
};
module.exports = function (eleventyConfig) {
	// async-friendly
	eleventyConfig.addCollection("myCollectionName", async (collectionsApi) => {
		// get unsorted items
		return collectionsApi.getAll();
	});
};

Return values

  • addCollection callbacks can return any arbitrary object type and it’ll be available as data in the template. Arrays, strings, objects—have fun with it.

Collection API Methods

The data collection gets passed to the callback. You can use it in all sorts of ways:

getAll()

Returns an array.

eleventy.config.js
export default function (eleventyConfig) {
	// Unsorted items (in whatever order they were added)
	eleventyConfig.addCollection("allMyContent", function (collectionsApi) {
		return collectionsApi.getAll();
	});
};
module.exports = function (eleventyConfig) {
	// Unsorted items (in whatever order they were added)
	eleventyConfig.addCollection("allMyContent", function (collectionsApi) {
		return collectionsApi.getAll();
	});
};

Example: getAll().filter()

eleventy.config.js
export default function (eleventyConfig) {
	// Filter using `Array.filter`
	eleventyConfig.addCollection("keyMustExistInData", function (collectionsApi) {
		return collectionsApi.getAll().filter(function (item) {
			// Side-step tags and do your own filtering
			return "myCustomDataKey" in item.data;
		});
	});
};
module.exports = function (eleventyConfig) {
	// Filter using `Array.filter`
	eleventyConfig.addCollection("keyMustExistInData", function (collectionsApi) {
		return collectionsApi.getAll().filter(function (item) {
			// Side-step tags and do your own filtering
			return "myCustomDataKey" in item.data;
		});
	});
};

Example: getAll().sort()

eleventy.config.js
export default function (eleventyConfig) {
	// Sort with `Array.sort`
	eleventyConfig.addCollection("myCustomSort", function (collectionsApi) {
		return collectionsApi.getAll().sort(function (a, b) {
			//return a.date - b.date; // sort by date - ascending
			return b.date - a.date; // sort by date - descending
			//return a.inputPath.localeCompare(b.inputPath); // sort by path - ascending
			//return b.inputPath.localeCompare(a.inputPath); // sort by path - descending
		});
	});
};
module.exports = function (eleventyConfig) {
	// Sort with `Array.sort`
	eleventyConfig.addCollection("myCustomSort", function (collectionsApi) {
		return collectionsApi.getAll().sort(function (a, b) {
			//return a.date - b.date; // sort by date - ascending
			return b.date - a.date; // sort by date - descending
			//return a.inputPath.localeCompare(b.inputPath); // sort by path - ascending
			//return b.inputPath.localeCompare(a.inputPath); // sort by path - descending
		});
	});
};

Curious where the date is coming from? Read more about Content Dates.

Note that the last example adding the myCustomSort collection will be available in your templates as collections.myCustomSort.

getAllSorted()

Returns an array.

eleventy.config.js
export default function (eleventyConfig) {
	// Use the default sorting algorithm (ascending by date, filename tiebreaker)
	eleventyConfig.addCollection("allMySortedContent", function (collectionsApi) {
		return collectionsApi.getAllSorted();
	});
};
module.exports = function (eleventyConfig) {
	// Use the default sorting algorithm (ascending by date, filename tiebreaker)
	eleventyConfig.addCollection("allMySortedContent", function (collectionsApi) {
		return collectionsApi.getAllSorted();
	});
};

Example: getAllSorted().reverse()

eleventy.config.js
export default function (eleventyConfig) {
	// Use the default sorting algorithm in reverse (descending dir, date, filename)
	// Note that using a template engine’s `reverse` filter might be easier here
	eleventyConfig.addCollection("myPostsReverse", function (collectionsApi) {
		return collectionsApi.getAllSorted().reverse();
	});
};
module.exports = function (eleventyConfig) {
	// Use the default sorting algorithm in reverse (descending dir, date, filename)
	// Note that using a template engine’s `reverse` filter might be easier here
	eleventyConfig.addCollection("myPostsReverse", function (collectionsApi) {
		return collectionsApi.getAllSorted().reverse();
	});
};

Note that while Array .reverse() mutates the array in-place, all Eleventy Collection API methods return new copies of collection arrays and can be modified without side effects to other collections. You can also use .toReversed() if you want to avoid mutations (Node 20+). However, you do need to be careful when using Array .reverse() in templates!

Example: getAllSorted().filter()

eleventy.config.js
export default function (eleventyConfig) {
	// Filter using `Array.filter`
	eleventyConfig.addCollection("onlyMarkdown", function (collectionsApi) {
		return collectionsApi.getAllSorted().filter(function (item) {
			// Only return content that was originally a markdown file
			let extension = item.inputPath.split(".").pop();
			return extension === "md";
		});
	});
};
module.exports = function (eleventyConfig) {
	// Filter using `Array.filter`
	eleventyConfig.addCollection("onlyMarkdown", function (collectionsApi) {
		return collectionsApi.getAllSorted().filter(function (item) {
			// Only return content that was originally a markdown file
			let extension = item.inputPath.split(".").pop();
			return extension === "md";
		});
	});
};

getFilteredByTag( tagName )

Returns an array.

eleventy.config.js
export default function (eleventyConfig) {
	// Get only content that matches a tag
	eleventyConfig.addCollection("myPosts", function (collectionsApi) {
		return collectionsApi.getFilteredByTag("post");
	});
};
module.exports = function (eleventyConfig) {
	// Get only content that matches a tag
	eleventyConfig.addCollection("myPosts", function (collectionsApi) {
		return collectionsApi.getFilteredByTag("post");
	});
};

getFilteredByTags( tagName, secondTagName, […] )

Retrieve content that includes all of the tags passed in. Returns an array.

eleventy.config.js
export default function (eleventyConfig) {
	// Get only content that matches a tag
	eleventyConfig.addCollection(
		"myTravelPostsWithPhotos",
		function (collectionsApi) {
			return collectionsApi.getFilteredByTags("post", "travel", "photo");
		}
	);
};
module.exports = function (eleventyConfig) {
	// Get only content that matches a tag
	eleventyConfig.addCollection(
		"myTravelPostsWithPhotos",
		function (collectionsApi) {
			return collectionsApi.getFilteredByTags("post", "travel", "photo");
		}
	);
};

getFilteredByGlob( glob )

Returns an array. Will match an arbitrary glob (or an array of globs) against the input file’s full inputPath (including the input directory).

INFO:
Note: getFilteredByGlob filters results returned from getAllSorted. It will not search the file system for new templates. It will not match files in your Includes directory or anything excluded by eleventyExcludeFromCollections.
INFO:
Note: getFilteredByGlob will not find files that are not supported by Eleventy. For example, a file with the extension .ray will be ignored even if it would match the glob.
eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.addCollection("onlyMarkdown", function (collectionApi) {
		return collectionApi.getFilteredByGlob("**/*.md");
	});

	eleventyConfig.addCollection("posts", function (collectionApi) {
		return collectionApi.getFilteredByGlob("_posts/*.md");
	});

	eleventyConfig.addCollection("posts", function (collectionApi) {
		// Also accepts an array of globs!
		return collectionApi.getFilteredByGlob(["posts/*.md", "notes/*.md"]);
	});
};
module.exports = function (eleventyConfig) {
	eleventyConfig.addCollection("onlyMarkdown", function (collectionApi) {
		return collectionApi.getFilteredByGlob("**/*.md");
	});

	eleventyConfig.addCollection("posts", function (collectionApi) {
		return collectionApi.getFilteredByGlob("_posts/*.md");
	});

	eleventyConfig.addCollection("posts", function (collectionApi) {
		// Also accepts an array of globs!
		return collectionApi.getFilteredByGlob(["posts/*.md", "notes/*.md"]);
	});
};