🧱 masonic

npm i masonic

A performant and versatile virtualized masonry grid for React based on Brian Vaughn's react-virtualized and further inspired by react-window.

Using Masonic, you're not just getting a component. You're getting the implementation details, as well, meaning advanced usage requiring little code is possible.

Features

• [x] Easy to use It takes two minutes to start creating your own masonry grid with this component. For real, check out the demo on CodeSandbox.
• [x] Blazing™ fast This component can seamlessly render tens of thousands of grid cells without lag via its virtualization algorithm and underlying data structures. For example, it uses a red black interval tree to determine which cells to render, based upon the scroll position and size of the window the grid is rendered in. Interval trees have O(log n + m) search performance 😱.
• [x] TypeScript Intellisense and type safety mean fewer bugs in your implementation.
• [x] Versatility All of <Masonry>'s implementation details (hooks, utilities) are exported, so you're not locked into to the default implementation. As you advance, it will be useful to have access to those internals. It's also possible to kick the virtualization out of the equation by providing an Infinity value to the overscanBy prop, though this would be a terrible idea for large lists.
• [x] Autosizing The default <Masonry> component will automatically resize itself and its items if the content of the grid cells changes or resizes. For example, when an image lazily loads this component will automatically do the work of recalculating the size of that grid cell. That said, you should try to premeasure things (including images) as often as possible in order to achieve the best user experience.

Quick Start

Check out the demo on CodeSandbox

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

Documentation

Components

Hooks

Utilities

Recipes

• Add infinite scrolling behavior to your Masonry component.
• Cells don't resize once they're measured? Build a Masonry grid without the resize observer.
• Reset <Masonry> layout when switching between routes within the same component.
  • Do the same with an advanced custom implementation using the usePositioner() hook.
• Render a Masonry component relative to a scrollable HTML element rather than the browser window.
• Add an isScrolling prop to cells

<Masonry>

An autosizing masonry grid that only renders items currently visible in the browser window. This component will change its column count to fit its container's width and will decide how many rows to render based upon the height of the browser window. To facilitate this, it uses useMasonry(), usePositioner(), useResizeObserver(),
useContainerPosition(), and useScroller() under the hood.

This is the "batteries included" option. It's the easiest way to get off and running with your app and a great stepping stone to more advanced implementations, should you need them.

Check out an example on CodeSandbox

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

Props

Required props

Column props

Props for tuning the column width, count, and gutter of your component.

Grid container props

These props customize how the grid container element is rendered.

Grid item props

Props that customize how individual grid item containers are rendered.

Callbacks

Other props

onRender() arguments

RenderComponentProps

<MasonryScroller>

A heavily-optimized component that updates useMasonry() when the scroll position of the browser window changes. This bare-metal component is used by <Masonry> above.

When would you use this? If you're building an advanced masonry grid implementation, but you don't want to deal with figuring out how to optimize the exchange between scroll position changes in the browser window and the useMasonry() hook.

Check out an example on CodeSandbox

import * as React from "react";
import { MasonryScroller, usePositioner, useContainerPosition } from "masonic";
import { useWindowSize } from "@react-hook/window-size";

const MyMasonry = (props) => {
  const containerRef = React.useRef(null);
  const [windowWidth, windowHeight] = useWindowSize();
  const { offset, width } = useContainerPosition(containerRef, [
    windowWidth,
    windowHeight,
  ]);
  const positioner = usePositioner({ width, columnWidth: 320 });

  return (
    <MasonryScroller
      positioner={positioner}
      // The distance in px between the top of the document and the top of the
      // masonry grid container
      offset={offset}
      // The height of the virtualization window
      height={windowHeight}
      // Forwards the ref to the masonry container element
      containerRef={containerRef}
      {...props}
    />
  );
};

Props

In addition to these props, this component accepts all of the props outlined in <Masonry> with exception to columnGutter, rowGutter, columnWidth, columnCount, maxColumntCount, ssrWidth, and ssrHeight.

<List>

This is a single-column <Masonry> component. That is, it uses the useMasonry() hook and other utilities to create a virtualized list.

Check out an example on CodeSandbox

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

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

const EasyListComponent = (props) => (
  <List items={items} rowGutter={32} render={ListCard} />
);

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

Props

In addition to these props, this component accepts all of the props outlined in <Masonry> with exception to columnGutter, columnWidth, columnCount, and maxColumnCount.

useMasonry(options)

This hook handles the render phases of the masonry layout and returns the grid as a React element.

Check out an example on CodeSandbox

import * as React from "react";
import { useWindowSize } from "@react-hook/window-size";
import {
  useMasonry,
  usePositioner,
  useContainerPosition,
  useScroller,
} from "masonic";

const MyMasonry = (props) => {
  const containerRef = React.useRef(null);
  const [windowWidth, height] = useWindowSize();
  const { offset, width } = useContainerPosition(containerRef, [
    windowWidth,
    height,
  ]);
  const { scrollTop, isScrolling } = useScroller(offset);
  const positioner = usePositioner({ width });

  return useMasonry({
    positioner,
    scrollTop,
    isScrolling,
    height,
    containerRef,
    ...props,
  });
};

Arguments

UseMasonryOptions

Required options

Grid container options

Grid item options

Callbacks

Other options

usePositioner(options, deps?)

This hook creates the grid cell positioner and cache required by useMasonry(). This is the meat of the grid's layout algorithm, determining which cells to render at a given scroll position, as well as where to place new items in the grid.

Check out an example on CodeSandbox

import * as React from "react";
import { usePositioner, useContainerPosition, MasonryScroller } from "masonic";

const MyMasonry = ({ columnWidth = 300, columnGutter = 16, ...props }) => {
  const { width, offset } = useContainerPosition();
  const positioner = usePositioner({ width, columnWidth, columnGutter });
  return <MasonryScroller positioner={positioner} offset={offset} {...props} />;
};

Arguments

UsePositionerOptions

Returns a Positioner

Positioner

export interface Positioner {
  /**
   * The number of columns in the grid
   */
  columnCount: number;
  /**
   * The width of each column in the grid
   */
  columnWidth: number;
  /**
   * Sets the position for the cell at `index` based upon the cell's height
   */
  set: (index: number, height: number) => void;
  /**
   * Gets the `PositionerItem` for the cell at `index`
   */
  get: (index: number) => PositionerItem | undefined;
  /**
   * Updates cells based on their indexes and heights
   * positioner.update([index, height, index, height, index, height...])
   */
  update: (updates: number[]) => void;
  /**
   * Searches the interval tree for grid cells with a `top` value in
   * betwen `lo` and `hi` and invokes the callback for each item that
   * is discovered
   */
  range: (
    lo: number,
    hi: number,
    renderCallback: (index: number, left: number, top: number) => void
  ) => void;
  /**
   * Returns the number of grid cells in the cache
   */
  size: () => number;
  /**
   * Estimates the total height of the grid
   */
  estimateHeight: (itemCount: number, defaultItemHeight: number) => number;
  /**
   * Returns the height of the shortest column in the grid
   */
  shortestColumn: () => number;
  /**
   * Returns all `PositionerItem` items
   */
  all: () => PositionerItem[];
}

export interface PositionerItem {
  /**
   * This is how far from the top edge of the grid container in pixels the
   * item is placed
   */
  top: number;
  /**
   * This is how far from the left edge of the grid container in pixels the
   * item is placed
   */
  left: number;
  /**
   * This is the height of the grid cell
   */
  height: number;
  /**
   * This is the column number containing the grid cell
   */
  column: number;
}

useScroller(offset?, fps?)

A hook for tracking whether the window is currently being scrolled and it's scroll position on the y-axis. These values are used for determining which grid cells to render and when to add styles to the masonry container that maximize scroll performance.

Check out an example on CodeSandbox

import * as React from "react";
import { useMasonry, usePositioner, useScroller } from "masonic";

const MyMasonry = (props) => {
  const containerRef = React.useRef(null);
  const { offset, width } = useContainerPosition(containerRef);
  const positioner = usePositioner({ width });
  const { scrollTop, isScrolling } = useScroller(offset);

  return useMasonry({
    ...props,
    containerRef,
    positioner,
    scrollTop,
    isScrolling,
  });
};

Arguments

Returns {scrollTop: number; isScrolling: boolean}

useContainerPosition(elementRef, deps?)

A hook for measuring the width of the grid container, as well as its distance from the top of the document. These values are necessary to correctly calculate the number/width of columns to render, as well as the number of rows to render.

Check out an example on CodeSandbox

import * as React from "react";
import { useWindowSize } from "@react-hook/window-size";
import { useContainerPosition, MasonryScroller } from "masonic";

const MyMasonry = (props) => {
  const containerRef = React.useRef(null);
  const [windowWidth, windowHeight] = useWindowSize();
  const { offset, width } = useContainerRect(
    containerRef,
    // In this example, we want to recalculate the `offset` and `width`
    // any time the size of the window changes
    [windowWidth, windowHeight]
  );

  return (
    <MasonryScroller
      width={width}
      height={windowHeight}
      containerRef={containerRef}
      {...props}
    />
  );
};

Arguments

Returns ContainerPosition

ContainerPosition

export interface ContainerPosition {
  /**
   * The distance in pixels between the top of the element in `elementRef` and the top of
   * the `document.documentElement`.
   */
  offset: number;
  /**
   * The `offsetWidth` of the element in `elementRef`.
   */
  width: number;
}

useScrollToIndex(positioner, options?)

A hook that creates a callback for scrolling to a specific index in the "items" array.

Check out an example on CodeSandbox

import * as React from "react";
import {
  useMasonry,
  usePositioner,
  useContainerPosition,
  useScroller,
  useScrollToIndex,
} from "masonic";

const MyMasonry = (props) => {
  const containerRef = React.useRef(null);
  const { offset, width } = useContainerPosition(containerRef);
  const { scrollTop, isScrolling } = useScroller(offset);
  const positioner = usePositioner({ width });
  const scrollToIndex = useScrollToIndex(positioner);

  React.useEffect(() => {
    if (props.scrollToIndex) {
      scrollToIndex(props.scrollToIndex);
    }
  }, [props.scrollToIndex, scrollToIndex]);

  return useMasonry({
    ...props,
    containerRef,
    positioner,
    scrollTop,
    isScrolling,
  });
};

Arguments

UseScrollToIndexOptions

Returns (index: number) => void

useResizeObserver(positioner)

This hook creates a resize observer that forces updates to the grid cell positions when mutations are made to cells affecting their height.

Check out an example on CodeSandbox

import * as React from "react";
import { useMasonry, usePositioner, useResizeObserver } from "masonic";

const MyMasonry = (props) => {
  const positioner = usePositioner({ width: 1024 });
  const resizeObserver = useResizeObserver(positioner);

  return useMasonry({
    positioner,
    resizeObserver,
    scrollTop,
    isScrolling,
    height,
    ...props,
  });
};

Arguments

Returns a ResizeObserver

useInfiniteLoader(loadMoreItems, options?)

A utility hook for seamlessly adding infinite scroll behavior to the useMasonry() hook and the components that use it. This hook invokes a callback each time the last rendered index surpasses the total number of items in your items array or the number defined in the totalItems option.

Check out an example on CodeSandbox

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

const InfiniteMasonry = (props) => {
  const [items, setItems] = useState([
    /* initial items */
  ]);
  const fetchMoreItems = async (startIndex, stopIndex, currentItems) => {
    const nextItems = await fetch(
      `/api/get-more?after=${startIndex}&limit=${startIndex + stopIndex}`
    );

    setItems((current) => [...current, ...nextItems]);
  };
  const maybeLoadMore = useInfiniteLoader(fetchMoreItems, {
    isItemLoaded: (index, items) => !!items[index],
  });

  return <Masonry {...props} items={items} onRender={maybeLoadMore} />;
};

Arguments

UseInfiniteLoaderOptions

Returns (startIndex: number, stopIndex: number, items: any[]) => any

createPositioner(columnCount, columnWidth, columnGutter, rowGutter)

Creates a cell positioner for the useMasonry() hook. The usePositioner() hook uses this utility under the hood.

Arguments

Returns Positioner

createResizeObserver(positioner, updater)

Creates a resize observer that forces updates to the grid cell positions when mutations are made to cells affecting their height.

Arguments

Returns a ResizeObserver

Differences from react-virtualized

There are actually quite a few differences between these components and the originals, despite the overall design being highly inspired by them.

1. The react-virtualized component requires a <CellMeasurer>, cellPositioner, and cellMeasurerCache and a ton of custom implementation to get off the ground. It's very difficult to work with. In Masonic this functionality is built in using resize-observer-polyfill for tracking cell size changes.

2. This component can auto-calculate the number of columns to render based upon the defined columnWidth property. The column count will update any time it changes.

3. The algoirthm for updating cell positions and sizes is much more efficient in this component because only specific cells and columns are updated when cell sizes change, whereas in the original a complete reflow has to triggered.

4. The API and internals are a complete rewrite and because of the above points, is much easier to use in my opinion.

Legacy Documentation

• Version 2 documentation

LICENSE

MIT