mason-it
v1.0.1
A lightweight, zero-dependency JavaScript library for instantly transforming a CSS grid into a responsive masonry layout. Just mason it.
75/weekUpdated 9 months agoMITUnpacked: 81.1 KB
Published by Druhin13
npm install mason-it
mason-it
Table of Contents
- About
- Why mason-it
- Features
- Installation
- Usage
- Advanced Configuration
- A Note on CSS for Optimal Results
- Browser Support
- License
- Final Thoughts
So you've wasted half your life trying to make a masonry layout work?
Me too! And let me tell you, I was _this close_ to throwing my laptop out the window.
4 different libraries, 27 Stack Overflow answers, and enough caffeine to kill a small horse later, I still had images overlapping, layouts breaking on resize, and a client breathing down my neck.
That's when I decided: screw it, I'll just make my own masonry library that actually works. And here we are!
mason-it was born from pure frustration and an unhealthy dose of spite.
_You're welcome._
Here's why you absolutely need this
Because other masonry libraries are allergic to your CSS Grid. There, I said it. While you’re trying to build a clean, modern layout with CSS Grid (you know, like a sane person)… these libraries are off in the 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.
Most masonry libraries basically say "That's a nice CSS Grid you've got there... would be a shame if someone COMPLETELY IGNORED IT." Then they proceed to hijack your layout with their own proprietary nonsense that requires a Ph.D in their documentation just to add a 12px gap between items.
#### But here's the revolutionary idea behind mason-it:
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.
That's it. No hostile takeover of your CSS. No "our way or the highway" attitude.
Now, do you really want to spend the next 3 hours reading documentation just to make some boxes line up nicely? Yeah, didn't think so.
Features
- Zero dependencies: Because your website shouldn't need to download half the internet just to display some boxes in a pretty pattern.
- 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.
- Actual 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 respects your grid.
- Silky-smooth updates: Leverages requestAnimationFrame for fluid layout adjustments when content changes or the window resizes, eliminating jank and layout shifts. Your users will thank you.
- Blazing fast & Ridiculously 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 when images load: Take that, other libraries! (not name-shaming anyone in particular… _uhm… uhm…_ it's in the name… _uhm hmm_)
- Microscopic footprint: The entire library is just over 6KB minified and gzipped. That's smaller than this README that you're reading, and I'm not even joking.
Installation
$3
You know the drill. You're probably already typing before you finished reading this:
``bash`
npm install mason-it
`js
// Import it, because this is what peak modern web development looks like
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(".standard-grid");
`
Boom. Done. Now go get some coffee.
For the Copy-Paste Professionals (CDN)
Just slap this
`
Usage
$3
`css
.standard-grid {
display: grid;
grid-template-columns: repeat(
auto-fill,
minmax(200px, 1fr)
); / Or your preferred column setup /
gap: 20px; / Your desired gap /
/ Recommended for true masonry behavior with varying item heights: /
align-items: start; / or align-items: flex-start /
grid-auto-rows: min-content; / If you want items to take up only as much space as their content needs /
}
`
_(See "A Note on CSS for Optimal Results" below for more on align-items and grid-auto-rows)_
$3
`bash`
data-mason-it
`html`
I'm a boring box
I'm taller than the other boxes and insecure about it
I'm short but mighty
mason-it will automatically initialize on elements with the data-mason-it attribute when the DOM is ready.
$3
That's literally it. If you were expecting more, sorry to disappoint.
Advanced Configuration (for the overachievers)
Want to delay the layout? Set a poll interval? Fine, here's how:
`html
data-mason-it="mason-delay:{500} mason-poll-interval:{2000}"
>
`
js
// JavaScript style, for the control freaks
// Ensure you call this after the DOM elements are available
MasonIt.init(".standard-grid", {
masonDelay: 500, // Wait 500ms before first layout
masonPollInterval: 2000, // Check for changes every 2 seconds (useful for dynamically added content if not using MutationObserver or manual refresh)
});
`Public API Methods:
js
// Manually initialize grids (if you're not using data-mason-it or need more control)
MasonIt.init(".another-grid");// Refresh layout (e.g., after adding/removing items or changing visibility)
// This is now super smooth thanks to requestAnimationFrame!
MasonIt.refresh(".standard-grid");
// Destroy layout (when your relationship with mason-it isn't working out)
MasonIt.destroy(".standard-grid");
// Enable debug mode (for when you absolutely must know what's happening under the hood)
MasonIt.debug(true); // Check your console!
// Get the version (why? I don't know, but here it is anyway)
console.log(MasonIt.version()); // Outputs "1.0.1"
// Count active grids (if you're into that sort of thing)
console.log(MasonIt.count());
`
A Note on CSS for Optimal Results
works by adjusting the margin-top of your grid items. To get the best "true" masonry effect where items retain their natural height and don't stretch to fill rows:1.
align-items: start; (or flex-start) on your grid container: This is crucial. CSS Grid's default align-items: stretch; will make all items in a row the same height, negating the visual masonry effect for height differences.
2. grid-auto-rows: min-content; (optional but recommended): This tells the grid rows to be only as tall as the tallest item in that implicit row _before_ mason-it does its magic. This can lead to more predictable layouts if your items have intrinsic heights.Example:
`css
.my-masonry-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
gap: 15px;
align-items: start; / Essential! /
/ grid-auto-rows: min-content; / / Consider this for content-driven heights /
}
` will then handle the vertical stacking.
So Your Grid Skills Are Actually Pretty Decent?
Perfect! That's exactly what we want. Unlike those other libraries that try to compensate for your supposed incompetence, mason-it actually _respects_ your CSS Grid skills. You know your way around
grid-template-columns and gap? Great! We're just here to add that final touch of masonry goodness.Think of us as the sous chef that doesn't try to take over your kitchen - you've done all the hard work creating a beautiful grid, and we just plate it up with a fancy masonry garnish. No judgment, no overriding your carefully crafted styles, just pure masonry enhancement.
The better your grid is designed, the better mason-it makes it look. We're in this together. You bring the grid skills, we bring the masonry magic. Deal?
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 window.getComputedStyle and window.requestAnimationFrame`.License (Legal Mumbo Jumbo)
It's MIT. Take it. Use it. Don't sue me if your website collapses like a poorly built brick wall. That's on you.
Final Thoughts
If you've read this far, congratulations on having way too much time on your hands. Now go make your grids look pretty, and remember: when in doubt, _just mason it_.