React Mosaicify

A lightweight React component for turning data into beautiful, grid-based visualizations.

Demo

Screen.Recording.2025-11-11.at.11.58.51.PM.mov

Features

• Lightweight: 8.8kb gzipped!
• Responsive Mosaic Grid: Dense, responsive grid of tiles to visualize data.
• Tooltip!: Customise your own tooltip to show on each cell.

Installation

npm install @andrehadianto/react-mosaicify

or

yarn add @andrehadianto/react-mosaicify

Getting Started

Here's a basic example of how to use Mosaicify in your React application:

import React from 'react';
import Mosaicify from '@andrehadianto/react-mosaicify';

const App = () => {
  const myData = [
    { id: '1', name: 'User One', imageUrl: 'https://example.com/image1.jpg' },
    { id: '2', name: 'User Two', imageUrl: 'https://example.com/image2.jpg' },
    { id: '3', name: 'User Three', imageUrl: 'https://example.com/image3.jpg' },
    // ... more data
  ];

  return (
    <div style={{ width: 400, height: 600 }}>
      <Mosaicify
        data={myData}
        withTooltip={(item) => <div>{item.name}</div>}
        tooltipPosition="bottom"
        tooltipAlignment="center"
      />
    </div>
  );
};

export default App;

API Docs

<Mosaicify /> Props

Prop	Type	Default	Description
data	Array<{ id: string; imageUrl: string; onClick?: () => void; [key]: string;}>	-	An array of data objects. Each object must have an id and imageUrl.
withTooltip	(item) => ReactNode	-	Optional function to render tooltip content for each grid item.
tooltipPosition	'top' | 'bottom' | 'left' | 'right'	'top'	Position of the tooltip.
tooltipAlignment	'start' | 'center' | 'end'	'center'	Alignment of the tooltip.
className	string	-	Optional CSS class to apply to the outer grid container.
gridClassName	string	-	Optional CSS class to apply to each grid item (both images and placeholders).
minTileWidth	number	14	The minimum width of each tile in pixels. The grid will fit as many columns as possible.
minNumberOfImages	number	5	The minimum number of images to display in the mosaic. Must be used with maxNumberOfImages.
maxNumberOfImages	number	10	The maximum number of images to display in the mosaic. Must be used with minNumberOfImages.
noRoundedCorners	boolean	false	If true, disables rounded corners on all tiles.