Macy.js – a lightweight, dependency-free masonry layout library

The past few weeks I’ve been working on a project that required a masonry layout. So I thought, rather than re-inventing the wheel, I would search for a plugin or component to do this for me.

After hours of sieving through a mountain of plugins I eventually got there, I found a plugin that worked almost exactly how I wanted; however there was one thing that was a little disappointing: the file size and dependencies. The plugin was 17KB (not massive, but not exactly small for what it does), and it also required jQuery.

But what I noticed most was how some of the plugins did one thing well, but another thing not so well. So I set to work on making my own to do exactly what I needed it to do, whilst fixing the things that others didn’t do so well. This is when Macy.js was born – the lightweight, dependency free masonry layout library. Best best of all: it’s only 4kb in size (minified)!

Macy.js is surprisingly easy to set up. With a quick inclusion of the script and one function call, you will be well on your way. But, rather that leave you to your own devices, here is a short guide on how to use it.

Installing & Using Macy.js

Macy.js is available through both Bower and npm.

bower install macy


npm install macy

Don’t use a package manager? Easy! Pop over to our GitHub Repository and download the latest release.

Once you have the script downloaded, require it as usual (directly into the DOM, or via your build process). We can now add some markup. Even though the markup should be the content you want, you will need to follow the general structure of [container-element] > [child element], so that Macy.js can work. Here is an example:

<div id=“macy-container”>
  <div class=“child-element”>lorem ipsum dolor sit amet.</div>
  <div class=“child-element”>lorem ipsum dolor sit amet.</div>
  <div class=“child-element”>lorem ipsum dolor sit amet.</div>

Now onto some JavaScript.

Macy.js comes with a variety of configurable options. To start Macy.js all we need to do is call Macy.init, but we do need to pass it some parameters.

There is only one required option, which is the container element. We can initialise it like this:

Macy.init({ container: “#macy-container” });

There are many more options you can add, including: breakpoints, column count, margin between each item, and you can even ask Macy.js to attempt to algorithmically equalise the column heights as closely as possible. For a full list of options, check out the documentation on GitHub.

You can view a demo of Macy.js in action here.

I wrote the script to try fix some problems that we encountered whilst trying to find an out of the box solution and I hope the script is useful for everyone. If you have any questions or suggestions please don’t hesitate to get in touch.

Thanks for reading.