@masonry-grid/react

RegularMasonryGrid

Standard masonry layout that stacks items by pulling them up to fill gaps.

import { RegularMasonryGrid as MasonryGrid, Frame } from '@masonry-grid/react'

<MasonryGrid
  frameWidth={200}
  gap={10}
>
  <Frame width={4} height={3}>
    <img src='...' />
  </Frame>
  {/* more frames... */}
</MasonryGrid>

Props

• frameWidth?: number | string - Minimum width of each frame. Used to calculate grid-template-columns. Can be a number (px) or string with units.
• gap?: number | string - Gap between items. Can be a number (px) or string with units.
• disabled?: boolean - Disable the masonry layout (no transforms/reordering will be applied).
• as?: ElementType - Render as a different element (default: 'div').
• All other HTML attributes are passed through.

BalancedMasonryGrid

Balanced masonry layout that reorders items inside rows to minimize overall grid height.

import { BalancedMasonryGrid as MasonryGrid, Frame } from '@masonry-grid/react'

<MasonryGrid
  frameWidth={200}
  gap={10}
>
  <Frame width={4} height={3}>
    <img src='...' />
  </Frame>
  {/* more frames... */}
</MasonryGrid>

Props

Same as RegularMasonryGrid.

Frame

Component for defining masonry grid item with aspect ratio.

import { Frame } from '@masonry-grid/react'

<Frame
  width={16}
  height={9}
  as='li'
>
  <img src='...' />
</Frame>

Props

• width: number - Width for aspect ratio calculation (not necessarily real pixel width).
• height: number - Height for aspect ratio calculation (not necessarily real pixel height).
• as?: ElementType - Render as a different element (default: 'div').
• All other HTML attributes are passed through.

SpannedMasonryGrid

Experemental CSS-only masonry layout that uses grid-row: span x to create masonry effect.

import { SpannedMasonryGrid as MasonryGrid, SpannedFrame as Frame } from '@masonry-grid/react'

<MasonryGrid
  frameWidth={200}
  gap={10}
>
  <Frame width={4} height={3}>
    <img src='...' />
  </Frame>
  {/* more frames... */}
</MasonryGrid>

Props

Same as RegularMasonryGrid, with an additional props:

• precision?: number - Precision for span calculation (default: 10). Affects how accurately frames will maintain their aspect ratios. Higher precision results in more accurate sizes but may impact performance and cause bugs in some browsers.
• innerStyle?: CSSProperties - Additional styles applied to the inner container that holds the frames.

SpannedFrame

Component for defining spanned masonry grid item with aspect ratio.

import { SpannedFrame as Frame } from '@masonry-grid/react'

<Frame
  width={16}
  height={9}
  as='li'
>
  <img src='...' />
</Frame>

Props

Same as Frame, with an additional prop:

• innerStyle?: CSSProperties - Additional styles applied to the inner container that holds the content.

useMasonryGrid

Hook for advanced use cases when you need direct access to the masonry grid instance.

import { useMasonryGrid } from '@masonry-grid/react'
import { RegularMasonryGrid } from '@masonry-grid/vanilla'

function CustomGrid() {
  const containerRef = useMasonryGrid<HTMLDivElement>({
    type: RegularMasonryGrid
  })

  return (
    <div
      ref={containerRef}
      style={{
        display: 'grid',
        overflow: 'hidden',
        gap: '10px'
      }}
    >
      {/* children */}
    </div>
  )
}