So you've wasted half your life trying to make a masonry layout?

Mason-it is a tiny, zero-dependency library born from pure frustration. It actually respects your CSS Grid (shocking, right?) while transforming it into a beautiful masonry layout. No hacky overrides, no bizarre margins. Just your grid, masoned.

Get Started Try the Demo

Just Released: v1.0.1 with improved rendering and hidden element detection

Mason-it: illustration of masons building a wall

Other masonry libraries are allergic to your CSS Grid.

The Problem

While you're trying to build a clean, modern layout with CSS Grid (you know, like a sane person)... most masonry libraries are off in a corner doing their own weird thing. Completely ignoring your carefully crafted grid settings. Adding bizarre margins. Treating CSS Grid like it's a communicable disease.

The Mason-it Solution

What if... and stay with me here... we just let you design your grid however the hell you want, and then just mason it? Crazy, right? You keep your grid-template-columns, you keep your gap property, you keep everything exactly how you designed it. We just make it masonry.

Standard CSS Grid

Items maintain row alignment, creating gaps

With Mason-it

Items flow perfectly without gaps

Here's why you absolutely need this

🧱

True CSS Grid Based

Unlike those other libraries that just pretend CSS Grid doesn't exist, like it's their ex from high school they're avoiding at the reunion. Mason-it actually respects your grid.

🚀

Zero Dependencies

Because your website shouldn't need to download half the internet just to display some boxes in a pretty pattern. Just 6KB minified and gzipped!

⚡

Stupidly Simple API

One attribute. ONE. data-mason-it. That's it. If you can't handle that, maybe try finger painting instead of web development.

🔄

Dynamic Content Ready

Uses MutationObserver to automatically update when content changes, because who wants to manually call refresh functions every time?

💧

Silky Smooth Updates v1.0.1

Leverages requestAnimationFrame for fluid layout adjustments when content changes or window resizes. No more janky shifts!

🙈

Handles Hidden Elements v1.0.1

Correctly recalculates when items use display: none. Take that, other libraries! (not name-shaming anyone in particular... uhm...)

📱

Blazing Fast & Responsive

So fast, it makes other libraries look like they're stuck in molasses. Recalculates layouts instantly, making it feel native and snappy.

🛠️

Doesn't Break on Images

No more layouts going haywire when images finally decide to load. Mason-it actually waits for your content to be ready.

Interactive Demo

Go ahead, poke around and see what happens. Add items, resize the container, or toggle visibility - mason-it handles it all with ease. This demo showcases v1.0.1's silky-smooth updates.

Add Items

Modify Items

Grid Configuration

Column Type:

Min Column Width:

200px

Grid Gap:

20px

Container Size

Current size: Auto

Mason-it Controls

Utilities

Auto-refresh on config change

Console Output

Current Grid CSS

.interactive-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 20px;
  align-items: start;
}

Installation

npm install mason-it

For the keyboard warriors - you're probably already typing before finishing reading this:

import MasonIt from 'mason-it';

// Magic time (call after your grid elements are in the DOM)
// e.g., inside a DOMContentLoaded listener or your framework's onMount/useEffect hook
MasonIt.init('.your-grid-selector', {
  masonDelay: 100, // Optional delay before first layout (ms)
  masonPollInterval: 0 // Optional polling interval (ms), 0 = disabled
});

For the copy-paste professionals - just slap this script tag at the end of your body:

<script src="https://cdn.jsdelivr.net/npm/mason-it@1.0.1/dist/mason-it.min.js"></script>

Elements with data-mason-it attribute will be automatically initialized. Or use the JavaScript API:

// When the DOM is ready:
MasonIt.init('.your-grid-selector');

Download the files directly from the GitHub release:

Check GitHub Release

Then include in your HTML:

<script src="path/to/mason-it.min.js"></script>

A Note on CSS for Optimal Results

Mason-it works by adjusting the margin-top of your grid items. For the best results, there's one critical CSS property you need:

.your-grid-container {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 20px;
  
  /* ⭐ THIS IS CRUCIAL ⭐ */
  align-items: start;
}

💡

Why align-items: start matters:

CSS Grid's default align-items: stretch will make all items in a row the same height, negating the visual masonry effect you're after. Using align-items: start tells the grid to align items to the top, letting them keep their natural height differences.

API Reference

For the overachievers - here's the complete API (which you probably won't need because the basic setup is so simple).

MasonIt.init(selector, [options])

Initializes Mason-it on the specified element(s).

Parameters:

selector

String CSS selector, Element, NodeList, or Array of elements.

options (optional)

Configuration object with the following properties:

masonDelay: Milliseconds to wait before initial layout (default: 0)
masonPollInterval: Interval in ms to check for content changes (default: 0, disabled)

                  // Initialize a specific grid with options
MasonIt.init('#my-grid', {
  masonDelay: 200,
  masonPollInterval: 1000
});

// Initialize multiple grids
MasonIt.init('.masonry-grids');
                

MasonIt.refresh([selector])

Manually refreshes the layout for the specified element(s) or all initialized elements if no selector is provided.

Parameters:

selector (optional): String CSS selector, Element, NodeList, or Array of elements. If omitted, refreshes all active Mason-it instances.

                  // Refresh a specific grid
MasonIt.refresh('#my-grid');

// Refresh all masonry grids
MasonIt.refresh();
                

MasonIt.destroy([selector])

Removes Mason-it functionality (when your relationship with mason-it isn't working out).

Parameters:

selector (optional): String CSS selector, Element, NodeList, or Array of elements. If omitted, destroys all active Mason-it instances.

                  // Remove Mason-it from a specific grid
MasonIt.destroy('#my-grid');

// Remove Mason-it from all grids
MasonIt.destroy();
                

MasonIt.debug(enable)

Enables or disables debug mode (for when you absolutely must know what's happening under the hood).

Parameters:

enable: Boolean value to enable (true) or disable (false) debug mode.

                  // Enable debug mode
MasonIt.debug(true);

// Disable debug mode
MasonIt.debug(false);
                

MasonIt.version()

Returns the current version (why? I don't know, but here it is anyway).

const version = MasonIt.version(); // "1.0.1"

MasonIt.count()

Returns the number of active Mason-it instances (if you're into that sort of thing).

const count = MasonIt.count(); // Number of active grids

HTML Data Attributes

For declarative initialization, just add this ONE attribute to your grid:

                  <!-- Basic usage -->
<div class="grid" data-mason-it></div>

<!-- With options -->
<div class="grid" data-mason-it="mason-delay:{500} mason-poll-interval:{2000}"></div>
                

Pro Tips

Dynamic Content

Mason-it uses MutationObserver to detect when items are added or removed. For other dynamic changes that don't trigger DOM mutations, call MasonIt.refresh() manually.

Images

If your grid contains images that load asynchronously (which they all do, let's be honest), consider using the masonDelay option or manually refreshing after images have loaded.

// Example: Refresh after images load
window.addEventListener('load', function() {
  MasonIt.refresh('.my-image-grid');
});

Animations & Transitions

If you're animating grid items, trigger a refresh after animations complete to ensure proper positioning:

element.addEventListener('transitionend', function() {
  MasonIt.refresh('#animated-grid');
});

Performance

For grids with many items (like, a ridiculous number of items), consider using the masonDelay option to defer initial layout until after critical page content has rendered. Your users won't notice, but your performance metrics will thank you.

Meeting Dominance

Start every stand-up by saying "I've optimized our masonry layouts with mason-it." Nobody will know what you're talking about, but they'll be too embarrassed to ask, and you'll seem productive for the rest of the sprint.

Dating Developers

If you're on a date with another developer, casually mention you use mason-it for all your masonry layouts. If they don't immediately propose marriage, they weren't worth your time anyway.

Browser Support

Works everywhere except Internet Explorer, because it's May 11, 2025 and if you're still supporting IE, you have bigger problems than masonry layouts. Mason-it relies on modern browser features like getComputedStyle and requestAnimationFrame.

Chrome

Supported

Firefox

Supported

Safari

Supported

Edge

Supported

Not Supported