<Masonry />

The default Masonry component — a thin wrapper around useMasonry that renders the grid and item elements for you. For a custom JSX structure (different outer element, extra attributes), use the hook directly.

Usage

import { Masonry } from 'kaskaid';
 
const DATA = [200, 600, 200, 400, 100, 600, 200, 400, 100, 600];
 
function App() {
  return (
    <Masonry
      data={DATA}
      estimateSize={() => 400}
      renderItem={({ item, index }) => <div style={{ height: item }}>{index}</div>}
    />
  );
}

Props

Accepts all UseMasonryOptions plus the following.

data

• Type: Data[]
• Required

Items to lay out. Each entry is passed back to renderItem as item.

renderItem

• Type: (props: VirtualItem & { item: Data }) => ReactNode
• Required

Renders the content of a single item. The library wraps the result in an absolutely-positioned element it measures and places into a lane.

Alongside the data element as item, the callback receives every field of the underlying TanStack VirtualItem — key, index, start, end, size, and lane. index maps into data exactly as before; the extras (notably lane, size, and start) previously forced consumers down to useMasonry just to read them.

estimateSize

• Type: (index: number) => number
• Required with ssr, optional otherwise

Estimated pixel height for the item at index. In client-only mode items are measured after mount, but providing an estimate is recommended for large lists so off-screen items contribute to the total scroll size and lane balance. With ssr it is the only height source for server HTML — without it every item collapses to 0.

gutter

• Type: number
• Default: 20

Gap between items in pixels, applied both between lanes and between items within a lane.

overscan

• Type: number
• Default: 3

Number of items rendered beyond the visible window, passed through to the underlying virtualizer.

scrollElementRef

• Type: RefObject<HTMLElement | null>
• Default: undefined (window scrolling)

Virtualize inside an overflow:auto element instead of the page. Own the scroll container yourself, pass its ref, and drop <Masonry> inside it — the grid then windows against that element's scroll position. See Scrolling in a Container for the full example and constraints. Mutually exclusive with ssr (container mode is client-only).

ssr

• Type: SSRConfig
• Default: undefined (client-only rendering)

Opt into server-rendered, pre-positioned items. See Server-Side Rendering.

import type { SSRConfig } from 'kaskaid';

className

• Type: string

Instance-specific selector for when multiple grids need different styling. Most usage can target [data-kaskaid-grid] and omit this — see Styling & Responsive Lanes.

style

• Type: CSSProperties

Merged after the library's grid styles. Do not override height, width, or position — the layout depends on them.

onEndReached

• Type: () => void

Callback fired when the last rendered item nears the end of data. Wraps useEndReached — pass your data-layer callback (fetchNextPage, setSize, fetchMore) directly. endReachedThreshold and endReachedDisabled are optional and refine when it fires. See Infinite Loading.

endReachedThreshold

• Type: number
• Default: 0

How many items from the end of data to fire onEndReached. Recommended to set ≥ overscan for prefetch-ahead (typically 3 or more). A value of 0 fires once the final item actually renders.

endReachedDisabled

• Type: boolean
• Default: false

Hard-suppresses onEndReached firing — wire it to your in-flight or has-more state (isFetchingNextPage, !hasNextPage).

ref

• Type: Ref<MasonryHandle>

Exposes the imperative handle, so imperative control does not require dropping to useMasonry:

import { useRef } from 'react';
import { Masonry, type MasonryHandle } from 'kaskaid';
 
const DATA = [200, 600, 200, 400, 100, 600, 200, 400];
 
function App() {
  const ref = useRef<MasonryHandle>(null);
 
  return (
    <>
      <button onClick={() => ref.current?.scrollToIndex(5, { align: 'center' })}>Jump to 5</button>
      <Masonry
        ref={ref}
        data={DATA}
        estimateSize={(i) => DATA[i]}
        renderItem={({ item, index }) => <div style={{ height: item }}>{index}</div>}
      />
    </>
  );
}

MasonryHandle exposes scrollToIndex (see useMasonry › scrollToIndex for its accuracy notes) and virtualizer. For a fully custom element structure, compose the hook directly instead. See Imperative Scrolling.