---

npm i masonic

---

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

Features

• Easy to use It only takes two minutes to start creating your own masonry grid with this component. For reals, check out the demo on CodeSandbox.
• Blazing™ fast This component can seamlessly render hundreds of thousands of grid items without issue via virtualization and intelligent data structures. It uses a red black interval tree to determine which grid items with O(log n + m) lookup performance to render based upon the scroll position and size of the window.
• TypeScript Woohoo, superior autocomplete and type safety means fewer bugs in your implementation.
• Versatility All of the autosizing <Masonry>'s constituent parts are provided via exports so you're not locked into to the implementation. At times 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 infinite value to the overscanBy prop, though this would be a terrible idea for large lists.
• Autosizing The grid will automatically resize itself and its items if the content of the grid items changes or resizes. For example, when an image lazily loads this component will automatically do the work of recalculating the size of that grid item using resize-observer-polyfill.

Quick Start

Check out the demo on CodeSandbox

1import {Masonry} from 'masonic'
2
3let i = 0
4const items = Array.from(Array(5000), () => ({id: i++}))
5
6const EasyMasonryComponent = props => (
7  <Masonry items={items} render={MasonryCard} />
8)
9
10const MasonryCard = ({index, data: {id}, width}) => (
11  <div>
12    <div>Index: {index}</div>
13    <pre>ID: {id}</pre>
14    <div>Column width: {width}</div>
15  </div>
16)

API

Components

Component	Description
<Masonry>	An autosizing masonry grid component that only renders items currently viewable in the 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 window. To facilitate this, it uses <FreeMasonry>, useContainerRect(), and useWindowScroller() under the hood.
<FreeMasonry>	A more flexible masonry grid component that lets you define your own width, height, scrollTop, and isScrolling props.
<List>	This is just a single-column <Masonry> component.

Hooks

Hook	Description
useInfiniteLoader()	A utility hook for seamlessly adding infinite scroll behavior to the <Masonry> component. 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 of this hook.
useContainerRect()	A hook used for measuring and tracking the width of the masonry component's container, as well as its distance from the top of your document. These values are necessary to correctly calculate the number/width of columns to render, as well as the number of rows to render.
useWindowScroller()	A hook used for measuring the size of the browser window, whether or not the window is currently being scrolled, and the window's scroll position. These values are used when calculating the number of rows to render and determining when we should disable pointer events on the masonry container to maximize scroll performance.

<Masonry>

An autosizing masonry grid component that only renders items currently viewable in the 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 window. To facilitate this, it uses <FreeMasonry>, useContainerRect(), and useWindowScroller() under the hood.

Props

Columns

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

Prop	Type	Default	Required?	Description
columnWidth	number	240	Yes	This is the minimum column width. Masonic will automatically size your columns to fill its container based on your provided columnWidth and columnGutter values. It will never render anything smaller than this defined width unless its container is smaller than its value.
columnGutter	number	0	No	This sets the amount (px) of vertical and horizontal space between grid items.
columnCount	number	undefined	No	By default, Masonic derives the column count from the columnWidth prop. However, in some situations it is nice to be able to override that behavior (e.g. when creating a <List>.

Item rendering

Props that dictate how individual grid items are rendered.

Prop	Type	Default	Required?	Description
render	React.ComponentClass|React.FC	undefined	Yes	The component provided here is rendered for each item of your items array (see below). The component here should handle the render props defined below.
items	any[]	undefined	Yes	An array of items to render. The data contained at each index is passed to the data prop of your render component. It is also passed to the onRender callback and the itemKey generator. Its length is used for determining the estimated height of the container.
itemHeightEstimate	number	300	No	This value is used for estimating the initial height of the masonry grid. it is vital to the UX of the scrolling behavior and in determining how many items to initially render, so its wise to set this value with some accuracy.
itemAs	React.ReactNode	"div"	No	Your render component is wrapped with an element that has a style prop which sets the position of the grid item in its container. This is the type of element created for that wrapper. One common use case would be changing this property to li and the Masonry component's as prop to ul.
itemStyle	React.CSSProperties	undefined	No	You can add additional styles to the wrapper discussed in itemAs by setting this property.
itemKey	(data: any, index: number) => string	(_, index) => index	No	The value returned here must be unique to the item. By default, the key is the item's index. This is ok if your collection of items is never modified. Setting this property ensures that the component in render is reused each time the masonry grid is reflowed. A common pattern would be to return the item's database ID here if there is one, e.g. data => data.id
overscanBy	number	2	No	This number is used for determining the number of grid items outside of the visible window to render. The default value is 2 which means "render 2 windows worth of content before and after the items in the visible window". A value of 3 would be 3 windows worth of grid items, so it's a linear relationship. Overscanning is important for preventing tearing when scrolling through items in the grid, but setting too high of a value may create too much work for React to handle, so it's best that you tune this value accordingly.

render props

These are the props provided to the component you set in your render prop.

Prop	Type	Description
data	any	This is the data contained at items[index] of your items prop array.
index	number	The index of the item in your items prop array.
width	number	The width of the collumn containing this component. This is super useful for doing things like determining the dimensions of images.

Customizing the container element

These props customize how the masonry grid element is rendered.

Prop	Type	Default	Required?	Description
as	React.ReactNode	"div"	No	This sets the element type of the masonry grid. A common use case would be changing this to ul and itemAs to li.
id	string	undefined	No	Add an ID to the masonry grid container.
className	string	undefined	No	Add a class to the masonry grid container.
style	React.CSSProperties	undefined	No	Add inline styles to the masonry grid container.
role	string	"grid"	No	Change the aria/a11y role of the container.
tabIndex	number	0	No	Change the tabIndex of the container. By default the container is tabbable.

Customizing the window for SSR

These are useful values to set when using SSR because in SSR land we don't have access to the width and height of the window, and thus have no idea how many items to render.

Prop	Type	Default	Required?	Description
initialWidth	number	1280	No	The width of the window in SSR.
initialHeight	number	720	No	The height of the window in SSR.

Callbacks

Prop	Type	Default	Required?	Description
onRender	(startIndex: number, stopIndex: number, items: any[]) => void	undefined	No	This callback is invoked any time the items rendered in the grid changes.

onRender() arguments

Argument	Type	Description
startIndex	number	The index of the first item currently being rendered in the window
stopIndex	number	The index of the last item currently being rendered in the window
items	any[]	The array of items you provided to the items prop

Methods

When a ref is provided to this component, you'll have access to the following imperative methods:

Method	Type	Description
clearPositions	() => void	Invoking this method will create a new position cache, clearing all previous stored position values. This is useful if you want the component to reflow when adding new items to the items array, however the best way to trigger a reflow is setting a different unique key prop on the <Masonry> component each time that happens.

---

<FreeMasonry>

This is a bare bones masonry grid without useWindowScroller() and useContainerRect() hooks doing any magic. It accepts all of the props from <Masonry> except initialWidth and initialHeight.

Additional props

Prop	Type	Default	Required?	Description
width	number	undefined	Yes	This sets the width of the grid.
height	number	undefined	Yes	This is the height of the grid's window. If you're rendering <FreeMasonry> inside of a scrollable div for example, this would be the height of that div.
scrollTop	number	undefined	Yes	The scroll position of the window <FreeMasonry> is rendering inside. Either the window object scroll position or the scroll position of say, a scrollable div you're rendering inside.
isScrolling	boolean	false	No	When this value is true, pointer-events: none; and will-change: contents, height; styles are applied to the grid to maximize scroll performance.
containerRef	((element: HTMLElement) => void) | React.MutableRefObject<HTMLElement | null>	undefined	No	Sets a ref prop on the grid container.

---

<List>

This is a single-column <Masonry> component. It accepts all of the properties defined in [<Masonry>], except columnGutter, columnWidth, and columnCount.

Additional props

Prop	Type	Default	Required?	Description
rowGutter	number	0	No	This sets the amount of vertical space in pixels between rendered list items.

---

useInfiniteLoader()

A React hook for seamlessly adding infinite scrolling behavior to <Masonry> and <List> components.

1import {Masonry, useInfiniteLoader} from 'masonic'
2import memoize from 'trie-memoize'
3
4const fetchMoreItems = memoize(
5  [{}, {}, {}],
6  (startIndex, stopIndex, currentItems) =>
7    fetch(
8      `/api/get-more?after=${startIndex}&limit=${startIndex + stopIndex}`
9    ).then(items => {
10      // do something to add the new items to your state
11    })
12)
13
14const InfiniteMasonry = props => {
15  const maybeLoadMore = useInfiniteLoader(fetchMoreItems)
16  const items = useItemsFromInfiniteLoader()
17  return <Masonry {...props} items={items} onRender={maybeLoadMore} />
18}

Arguments

Argument	Type	Description
loadMoreItems	(startIndex: number, stopIndex: number, items: any[]) => any	This callback will be invoked when more items must be loaded. It may be called multiple times in reaction to a single scroll event. As such, you are expected to memoize/track whether or not you've already received the startIndex, stopIndex, items values to prevent loading data more than once.
options	InfiniteLoaderOptions	Configuration object for your loader, see InfiniteLoaderOptions below.

InfiniteLoaderOptions

Property	Type	Default	Description
isItemLoaded	(index: number, items: any[]) => boolean	(index, items) => items[index] !== undefined	A callback responsible for determining the loaded state of each item. Return true if the item has already been loaded and false if not.
minimumBatchSize	number	16
threshold	number	16	The default value of 16 means that data will start loading when a user scrolls within 16 items of the end of your items prop array.
totalItems	number	9E9	The total number of items you'll need to eventually load (if known). This can be arbitrarily high if not known (e.g., the default value).

---

useWindowScroller()

A hook used for measuring the size of the browser window, whether or not the window is currently being scrolled, and the window's scroll position. These values are used when calculating the number of rows to render and determining when we should disable pointer events on the masonry container to maximize scroll performance.

1import React from 'react'
2import {FreeMasonry, useWindowScroller, useContainerRect} from 'masonic'
3
4const MyCustomMasonry = props => {
5  const {width, height, scrollY, isScrolling} = useWindowScroller(),
6    [rect, containerRef] = useContainerRect(width, height)
7
8  return React.createElement(
9    FreeMasonry,
10    Object.assign(
11      {
12        width: rect.width,
13        height,
14        scrollTop: Math.max(0, scrollY - (rect.top + scrollY)),
15        isScrolling,
16        containerRef,
17      },
18      props
19    )
20  )
21}

Arguments

Argument	Type	Description
initialWidth	number	The width of the window when render on the server side. This has no effect client side.
initialHeight	number	The height of the window when render on the server side. This has no effect client side.
options	WindowScrollerOptions	A configuration object for the hook. See WindowScrollerOptions below.

WindowScrollerOptions

1interface WindowScrollerOptions {
2  size?: {
3    // Debounces for this amount of time in ms
4    // before updating the size of the window
5    // in state
6    //
7    // Defaults to: 120
8    wait?: number
9  }
10  scroll?: {
11    // The rate in frames per second to update
12    // the state of the scroll position
13    //
14    // Defaults to: 8
15    fps?: number
16  }
17}

Returns WindowScrollerResult

1interface WindowScrollerResult {
2  // The width of the browser window
3  width: number
4  // The height of the browser window
5  height: number
6  // The scroll position of the window on its y-axis
7  scrollY: number
8  // Is the window currently being scrolled?
9  isScrolling: boolean
10}

---

useContainerRect()

A hook used for measuring and tracking the width of the masonry component's container, as well as its distance from the top of your document. These values are necessary to correctly calculate the number/width of columns to render, as well as the number of rows to render.

1import React from 'react'
2import {FreeMasonry, useWindowScroller, useContainerRect} from 'masonic'
3
4const MyCustomMasonry = props => {
5  const {width, height, scrollY, isScrolling} = useWindowScroller(),
6    [rect, containerRef] = useContainerRect(width, height)
7
8  return React.createElement(
9    FreeMasonry,
10    Object.assign(
11      {
12        width: rect.width,
13        height,
14        scrollTop: Math.max(0, scrollY - (rect.top + scrollY)),
15        isScrolling,
16        containerRef,
17      },
18      props
19    )
20  )
21}

Arguments

Argument	Type	Description
windowWidth	number	The width of the window. Used for updating the ContainerRect when the window's width changes.
windowHeight	number	The height of the window. Used for updating the ContainerRect when the window's height changes.

Returns [ContainerRect, (element: HTMLElement) => void]

ContainerRect

Property	Type	Description
top	number	The top value from element.getBoundingClientRect()
width	number	The width value from element.getBoundingClientRect()

---

Differences from react-virtualized/Masonry

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 will 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 implementation for updating cell positions and sizes is also 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 is triggered.

4. The API is a complete rewrite and because of much of what is mentioned above, is much easier to use in my opinion.

LICENSE

MIT