Meta Mosaic: A Lightweight, Interactive Mosaic Layout for React

Arbaj Ansari — Wed, 28 Jan 2026 19:02:57 +0000

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

🚀 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>
  );
}

Done. No layout math. No hacks.

🧠 How it works (simple mental model)

Instead of relying on CSS tricks:

Measure item heights
Distribute items to the shortest column
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} />

Memoize large lists

const items = useMemo(() => data, [data]);

Use lazy loading

loading="lazy"

📊 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!

DEV Community: Arbaj Ansari