DEV Community

Arbaj Ansari
Arbaj Ansari

Posted on

Meta Mosaic: A Lightweight, Interactive Mosaic Layout for React

#webdev #programming #opensource #javascript

If you’ve ever tried building a Pinterest-style / collage / mosaic layout in React, you already know the pain:

  • manual column math
  • uneven heights
  • reflows on resize
  • messy CSS hacks
  • heavy libraries

I faced the same problem… so I built Meta Mosaic.

A small, fast, and flexible React image mosaic/grid layout library that just works.

✨ What is Meta Mosaic?

Meta Mosaic helps you render:

  • image galleries
  • portfolios
  • dashboards
  • feeds
  • cards with dynamic heights

in a clean masonry/mosaic style layout with minimal setup.

Think:

"CSS Grid simplicity + Masonry layout behavior + React control"

❌ The problem with existing solutions

Most options I tested had issues:

1. Pure CSS columns

  • items jump around
  • bad ordering
  • poor responsiveness

2. Heavy masonry libraries

  • big bundle size
  • DOM measurements on every render
  • poor React integration

3. DIY logic

  • complex calculations
  • hard to maintain
  • edge cases everywhere

I wanted something:

✅ lightweight
✅ React-first
✅ predictable ordering
✅ responsive
✅ simple API

So I built it.

🧩 Features

  • ⚡ Lightweight
  • ⚛️ Built for React (not DOM hacks)
  • 📱 Responsive columns
  • 🧠 Smart height balancing
  • 🪶 Minimal dependencies
  • 🎨 Works with images, cards, or any JSX
  • 🔧 Fully customizable

📦 Install 

npm install meta-mosaic
Enter fullscreen mode Exit fullscreen mode

🚀 Basic Usage 

import { Mosaic } from "meta-mosaic";

const images = [
  "/img/1.jpg",
  "/img/2.jpg",
  "/img/3.jpg",
];

export default function Gallery() {
  return (
    <Mosaic columns={3} gap={12}>
      {images.map((src) => (
        <img key={src} src={src} alt="" />
      ))}
    </Mosaic>
  );
}
Enter fullscreen mode Exit fullscreen mode

Done. No layout math. No hacks.

🧠 How it works (simple mental model)

Instead of relying on CSS tricks:

  1. Measure item heights
  2. Distribute items to the shortest column
  3. Render columns

It’s basically:

"Greedy column balancing algorithm"

Which keeps your grid visually even and stable.

🎯 Where you can use it

  • portfolios
  • product grids
  • photo galleries
  • dashboards
  • content feeds
  • admin panels

Anywhere you need variable height cards.

⚖️ Why not just CSS Masonry?

Native CSS masonry is still inconsistent across browsers.

Meta Mosaic gives you:

  • stable behavior today
  • predictable rendering
  • React control

No waiting for browser support.

🛠 Tips (learned the hard way)

Always add image dimensions

Prevents layout shift.

<img width={300} height={200} />
Enter fullscreen mode Exit fullscreen mode

Memoize large lists 

const items = useMemo(() => data, [data]);
Enter fullscreen mode Exit fullscreen mode

Use lazy loading 

loading="lazy"
Enter fullscreen mode Exit fullscreen mode

📊 Performance

  • minimal re-renders
  • no heavy observers
  • small bundle
  • works smoothly with 1000+ items

💬 Why I built this

I wanted a:

"drop‑in mosaic layout for React that doesn’t fight me"

So I built Meta Mosaic for my own projects… then open-sourced it.

If you build galleries, dashboards, or feeds — this might save you hours.

🔗 Try it

  • GitHub: (add repo link)
  • NPM: (add package link)

❤️ Feedback welcome

If you try it, I’d love:

  • issues
  • suggestions
  • feature requests
  • stars ⭐

Happy building!

Top comments (0)