useMasonry

The headless flavor of the library. It owns the virtualizer, lane-count tracking, and the SSR fallback chain, and returns prop bags you spread onto your own JSX — <Masonry /> is just a thin wrapper around it.

Usage

import { useMasonry } from 'kaskaid';
 
const DATA = [200, 600, 200, 400, 100, 600, 200, 400, 100, 600];
 
function App() {
  const { gridProps, getItemProps, items } = useMasonry({
    data: DATA,
    estimateSize: () => 400,
  });
 
  return (
    <section {...gridProps}>
      {items.map((item) => (
        <article key={item.key} {...getItemProps(item)}>
          <div style={{ height: DATA[item.index] }}>{item.index}</div>
        </article>
      ))}
    </section>
  );
}

Options

UseMasonryOptions<Data> is discriminated on ssr: opting into SSR makes estimateSize required so server output is well-formed.

data

• Type: Data[]
• Required

Items to lay out. The hook only reads data.length; your render code indexes into it.

estimateSize

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

Estimated pixel height for the item at index. Recommended for large lists even in client-only mode, so off-screen sizes contribute to getTotalSize() and lane balance.

gutter

• Type: number
• Default: 20

Gap between items in pixels.

overscan

• Type: number
• Default: 3

Number of items rendered beyond the visible window.

ssr

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

SSR rendering configuration — see <Masonry /> › ssr. Mutually exclusive with scrollElementRef (SSR is window-only).

scrollElementRef

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

Virtualize inside an overflow:auto element instead of the page. Pass a ref to the scroll container and the grid windows against that element's scroll position; omit it for the default window scrolling. See Scrolling in a Container.

Returns

UseMasonryReturn:

gridProps

• Type: MasonryGridProps

Spread onto the grid root element. Carries the ref, the sizing/positioning style, and the data-kaskaid-grid / data-kaskaid-lanes attributes.

getItemProps

• Type: (item: VirtualItem) => MasonryItemProps

Returns props for a single item — spread the result onto the item element and pass key={item.key} separately. Carries the measurement ref, data-index, data-kaskaid-item, and the absolute-positioning style.

items

• Type: VirtualItem[]

Items to render this frame. During SSR / pre-mount this is the first ssr.itemCount entries from the measurements cache; after mount it is the real visible window from the virtualizer.

lanes

• Type: number

Current lane count — resolved from the --lanes CSS custom property post-mount, or the fallback (ssr.lanes, default 4) before that.

virtualizer

• Type: Virtualizer<HTMLElement, Element> | Virtualizer<Window, Element>

The underlying TanStack virtualizer — an escape hatch for imperative APIs beyond scrollToIndex (e.g. scrollToOffset, measure). Element-scoped when scrollElementRef is set, otherwise window-scoped.

scrollToIndex

• Type: (index: number, options?: ScrollToOptions) => void

Scrolls so index is positioned per options.align (default 'auto': nearest edge, no-op if already visible). Referentially stable across renders — safe to pass in an effect's dependency array. A thin forward to TanStack Virtual's own method — options is its ScrollToOptions (align: 'start' | 'center' | 'end' | 'auto', behavior: 'auto' | 'smooth').

Accuracy is bounded by estimateSize — a cold jump to a far index can land off-target. See Imperative Scrolling for a runnable example and the full accuracy characterization.

scrollOffset

• Type: number

Current scroll offset (px) of the active scroller — the window or, in container mode, the scrollElementRef element. Reactive: re-renders on scroll. 0 before the virtualizer has measured. Use for scroll-aware UI (minimaps, position indicators) without attaching your own scroll listener.

viewportSize

• Type: number

Viewport height (px) of the active scroller — the window or, in container mode, the scrollElementRef element. Reactive: re-renders as the viewport resizes. 0 before the virtualizer has measured. Pairs with scrollOffset.

Types

All public types are exported from the package root:

import type {
  SSRConfig,
  UseMasonryOptions,
  UseMasonryReturn,
  MasonryGridProps,
  MasonryItemProps,
} from 'kaskaid';