🧩 MetaMosaic

A simple and responsive React component to create a mosaic grid of images — with background image, custom styles, and click dialog support.

🚀 Installation

npm install meta-mosaic
# or
yarn add meta-mosaic

Then import it in your project:

import { MetaMosaic } from "meta-mosaic";
import "meta-mosaic/dist/meta-mosaic.css";

⚡ Quick Example

import React from "react";
import { MetaMosaic } from "meta-mosaic";
import "meta-mosaic/dist/meta-mosaic.css";

const images = Array.from({ length: 400 }, (_, i) => ({
  id: i + 1,
  link: `https://picsum.photos/id/${101 + i}/400/300`,
  title: `Image ${i + 1}`,
}));

const bgImage =
  "https://i.etsystatic.com/32237469/r/il/72bad1/4009560313/il_570xN.4009560313_q4ps.jpg";

function App() {
  return (
    <MetaMosaic
      images={images}
      size={20}
      bgImageUrl={bgImage}
      gridWrapperClassName="custom-mosaic-wrapper"
      gridWrapperStyle={{ boxShadow: "0 0 1em rgba(255,255,255,0.5)" }}
      bgPosition="center 8px"
      width={{ xs: 350, md: 500, lg: 650 }}
      height={{ xs: 350, md: 500, lg: 650 }}
      setDialog={(img) => (
        <div>
          <h2>{img.id}</h2>
          <h6 style={{ color: "red" }}>{img.title}</h6>
          <img src={img.link} alt={img.title} />
        </div>
      )}
    />
  );
}

export default App;

🧩 Props Guide

| Prop | Type | Description | | ------------------------ | ---------- | ---------------------------------------------------------------------------------- | | images | Array | List of images to display in mosaic. Each image should have { id, link, title }. | | size | number | Defines number of rows and columns. Example: size={4} → 4x4 grid. | | bgImageUrl | string | Background image for the mosaic layout. | | gridWrapperClassName | string | Add your custom class to the grid wrapper. | | gridWrapperStyle | object | Inline CSS styles for grid wrapper. | | bgPosition | string | Adjust the background image position (e.g. "center 8px"). | | width | object | Responsive width based on breakpoints: { xs, md, lg }. | | height | object | Responsive height based on breakpoints: { xs, md, lg }. | | setDialog | function | Custom component that opens when clicking a mosaic cell. |

💡 Example: setDialog

setDialog={(img) => (
  <div>
    <h2>{img.id}</h2>
    <h6 style={{ color: 'red' }}>{img.title}</h6>
    <img src={img.link} alt={img.title} />
  </div>
)}

This function runs when a user clicks on a cell. You can render any custom component here.

🪄 Responsive Behavior

You can set different width and height values for small, medium, and large screens:

width={{ xs: 350, md: 500, lg: 650 }}
height={{ xs: 350, md: 500, lg: 650 }}

The component adjusts automatically based on screen size.

📦 Changelog

v1.0.11 — (2025-11-09)

✨ New Features

• Added all props: images, size, bgImageUrl, gridWrapperClassName, gridWrapperStyle, bgPosition, width, height, and setDialog.
• Fully responsive and customizable grid.
• Clickable mosaic cells with custom dialog support.

🧠 Tips

• Use high-quality images for better visual effect.
• The bgImageUrl should have similar aspect ratio as your grid.
• Combine gridWrapperStyle with className for fine-tuned control.

Alternatives & Comparisons

• react-mosaic-component - More complex, for window management
• @tilework/mosaic - E-commerce focused
• react-photo-gallery - Simpler, no dialog support
• react-grid-gallery - Heavy bundle, more features

meta-mosaic is lightweight and perfect for simple, responsive image grids with metadata.

📜 License

MIT © MetaMosaic