masonic

masonic is a virtualized masonry grid component for React. Key features include:

• Virtualization: Uses a red-black interval tree for O(log n + m) lookup performance, allowing it to render hundreds of thousands of items efficiently.
• Autosizing: The grid automatically recalculates item sizes if content changes or resizes (e.g., when an image lazily loads).
• TypeScript Support: Provides full type safety and autocomplete.
• Versatility: Provides access to constituent parts of the <Masonry> component. You can disable virtualization by providing an infinite value to the overscanBy prop (not recommended for large lists).

While inspired by react-virtualized/Masonry, Masonic provides a significantly different developer experience:

• Built-in Size Tracking: Unlike react-virtualized, which requires manual setup of <CellMeasurer>, cellPositioner, and cellMeasurerCache, Masonic has built-in functionality for tracking cell size changes using resize-observer-polyfill.
• Automatic Column Calculation: Masonic automatically calculates the number of columns to render based on the columnWidth property. The column count updates dynamically whenever columnWidth changes.
• Efficient Reflows: When cell sizes change, Masonic only updates the specific cells and columns affected, whereas the original triggers a complete reflow.
• Simplified API: The API has been completely rewritten to be more intuitive and easier to implement.

The <Masonry> component is a "batteries included" masonry grid. It is the easiest way to implement a masonry layout because it handles all implementation details automatically: it adjusts column counts based on container width and determines row counts based on the browser window height. It uses several internal hooks like useMasonry, usePositioner, and useScroller to manage layout and performance.

import * as React from "react";
import { Masonry } from "masonic";

let i = 0;
const items = Array.from(Array(5000), () => ({ id: i++ }));

const EasyMasonryComponent = (props) => (
  <Masonry items={items} render={MasonryCard} />
);

const MasonryCard = ({ index, data: { id }, width }) => (
  <div>
    <div>Index: {index}</div>
    <pre>ID: {id}</pre>
    <div>Column width: {width}</div>
  </div>
);

Install the masonic package using npm to use the virtualized masonry grid component in your React project.

npm i masonic

You can quickly implement a masonry grid using the <Masonry /> component. You need to provide an items array and a render function that defines how each item should be displayed. The render function receives index, data (the item itself), and width as props.

Note: For large lists, masonic uses a red-black interval tree for high-performance virtualization, ensuring smooth scrolling even with tens of thousands of items.

import * as React from "react";
import { Masonry } from "masonic";

let i = 0;
const items = Array.from(Array(5000), () => ({ id: i++ }));

const EasyMasonryComponent = (props) => (
  <Masonry items={items} render={MasonryCard} />
);

const MasonryCard = ({ index, data: { id }, width }) => (
  <div>
    <div>Index: {index}</div>
    <pre>ID: {id}</pre>
    <div>Column width: {width}</div>
  </div>
);

Customize the grid container element or provide initial dimensions for Server-Side Rendering (SSR):

Container Customization:

• as (React.ReactNode, default: "div"): The element type of the masonry grid.
• id, className, style, role, tabIndex: Standard HTML attributes for the container.

SSR Support: Since SSR environments lack window dimensions, provide these to prevent layout shifts:

• initialWidth (number, default: 1280)
• initialHeight (number, default: 720)

Use these props to tune the layout of the <Masonry> grid:

• columnWidth (number, default: 240): The minimum width for a column. The component will automatically fill the container using this value.
• columnGutter (number, default: 0): The amount of space (px) between grid items (both vertical and horizontal).
• columnCount (number): An optional override to force a specific number of columns, useful when creating a <List>.