Masonry creates a deterministic grid layout, positioning items based on available vertical space. It contains performance optimizations like virtualization and support for infinite scrolling.

also known as Grid, Image List

Figma:

Web:

iOS:

Android:

A11y:

Props

Component props
Name
Type
Default
Item
Required
React.ComponentType<{|
  data: T,
  itemIdx: number,
  isMeasuring: boolean,
|}>
-

A React component (or stateless functional component) that renders the item you would like displayed in the grid. This component is passed three props: the item's data, the item's index in the grid, and a flag indicating if Masonry is currently measuring the item. Note that this must be a stable reference! If using a component declared within a parent function component, you must use useCallback to ensure a stable reference.

items
Required
$ReadOnlyArray<T>
-

An array of items to display that contains the data to be rendered by <Item />.

columnWidth
number
-

The preferred/target item width. If 'flexible' is set, the item width will
grow to fill column space, and shrink to fit if below min columns.

gutterWidth
number
-

The amount of vertical and horizontal space between each item, specified in pixels.

layout
"basic" | "basicCentered" | "flexible" | "serverRenderedFlexible" | "uniformRow"
-

basic: Left aligned masonry layout.
basicCentered: Center aligned masonry layout.
flexible: Item width grows to fill column space and shrinks to fit if below min columns.
serverRenderedFlexible: Item width grows to fill column space and shrinks to fit if below min columns. Main differerence with flexible is that we do not store the initial measurement. More context in #2084
uniformRow: Items are laid out in a single row, with all items having the same height.

loadItems
false
| ((
    ?{|
      from: number,
    |},
  ) => void | boolean | { ... })
-

A callback which the grid calls when we need to load more items as the user scrolls.
The callback should update the state of the items, and pass those in as props
to this component.
Note that scrollContainer must be specified.

measurementStore
typeof MeasurementStore
-

Masonry internally caches item sizes/positions using a measurement store. If measurementStore is provided, Masonry will use it as its cache and will keep it updated with future measurements. This is often used to prevent re-measurement when users navigate away and back to a grid. Create a new measurement store with Masonry.createMeasurementStore().

minCols
number
-

Minimum number of columns to display.

scrollContainer
() => HTMLElement
-

A function that returns a DOM node that Masonry uses for on-scroll event subscription. This DOM node is intended to be the most immediate ancestor of Masonry in the DOM that will have a scroll bar; in most cases this will be the window itself, although sometimes Masonry is used inside containers that have overflow: auto. scrollContainer is optional, although it is required for features such as virtualize and loadItems.
This is required if the grid is expected to be scrollable.

virtualBoundsBottom
number
-

If virtualize is enabled, Masonry will only render items that fit in the viewport, plus some buffer. virtualBoundsBottom allows customization of the buffer size below the viewport, specified in pixels.

virtualBoundsTop
number
-

If virtualize is enabled, Masonry will only render items that fit in the viewport, plus some buffer. virtualBoundsTop allows customization of the buffer size above the viewport, specified in pixels.

virtualBufferFactor
number
-

If virtualize is enabled, Masonry will only render items that fit in the viewport, plus some buffer. virtualBufferFactor allows customization of the buffer size, specified as a multiplier of the container height. It specifies the amount of extra buffer space for populating visible items. For example, if virtualBufferFactor is 2, then Masonry will render items that fit in the viewport, plus 2x the viewport height.

virtualize
boolean
-

Specifies whether or not Masonry dynamically adds/removes content from the grid based on the user's viewport and scroll position. Note that scrollContainer must be specified when virtualization is used.

Accessibility

Fluid number of columns

The number of columns in this grid changes responsively based on the width of the parent.

<Masonry
  Item={Item}
  items={this.state.pins}
  loadItems={this.loadItems}
  minCols={1}
/>

Flexible item width

When layout is set to flexible, the item width will shrink/grow to fill the container. This is great for responsive designs.

<Masonry layout="flexible" Item={Item} items={items} minCols={1} />

Non-flexible item width

When the flexible property is omitted, the item width will be fixed to columnWidth.

<Masonry Item={Item} items={items} minCols={1} />

Uniform row heights

Using the uniformRow layout.

<Masonry Item={Item} items={items} layout="uniformRow" />;

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma across all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.