Collection objects provide a set of utility methods for working with groups of items, such as components or documentation pages.


It's important to note that Collection objects are immutable - when you call a filter method or similar you get back a new Collection object, leaving the original object intact.

The documentation below assumes that you already have a reference to a collection object, such as the component source object:

const collection = fractal.components;

Collections are themselves iterators, so you can iterate over them directly using expressions such as the new ES2015 for...of loops:

for (let item of collection) {

Collections can contain sub-collections within them. If you want to iterate over all items in a collection (as opposed to only the collection's direct children) you can use the .flatten() method:

for (let item of collection.flatten()) {



Find an item within the collection. Search is recursive down through any sub-collections.

const button = collection.find('@button');
const sameButton = collection.find('handle', 'button');
const sameButtonAgain = collection.find(function(item){
    return item.handle === 'button';


Returns a new collection that is the result of filtering the old collection using the predicatearguments.

const hiddenItems = collection.filter('isHidden', true);
const taggedWithFoo = collection.filter(function(){
    return item.tags.includes('foo');


Return a new collection created by recursing down through the original collections items and all its sub-collections and extracting out all non-collection entities.

const allItems = collection.flatten();


Same as flatten, except in the case of component collections will also pull out any variants of the components as well as the root components themselves.

const allVariants = collection.flattenDeep();


Returns a new collection that is the result of ordering the old collection using according to the arguments supplied.

const subCollectionsFirstThenByTitle = collection.orderBy(['isCollection', 'title'], ['asc', 'asc']);


Iterate over all of the items in the collection, calling the callback for each one.



Return a new collection made up of mapped items from the source collection.

const newCollection = collection.forEach(function(item){
    collection.title = collection.title.toUpperCase();
    return collection;


Get the first item in the collection

const first = collection.first();


Get the last item in the collection

const first = collection.last();


  • pos: Integer

Get the item at position pos in the collection (collections are zero-indexed).

const third = collection.eq(2);


Converts the collection to an array of items, as opposed to an iteratable object.

const items = collection.toArray();


Returns a simplified, 'template engine friendly' object representation of the collection and all it's children, recursively.

const items = collection.toJSON();


Turns the collection into a Gulp-compatible Vinyl stream.

const stream = collection.toStream();



The number of items in the collection (does not include items within sub-collections).

Last Updated: 9/5/2018, 9:49:47 AM