Hooks

Most apps should use the components directly. Hooks are exported for advanced integrations, custom diagnostics, and specialized layout surfaces.

usePositioner

import { usePositioner, type UsePositionerOptions } from 'masonix';

const positioner = usePositioner({
  columnCount: 3,
  columnWidth: 240,
  gap: 16,
});

Creates a shortest-column positioner for a known column count, column width, and gap. Use this only when building custom layout primitives around Masonix placement behavior. set(index, height) accepts sparse indexes and updates an existing index instead of inserting it twice. Reported column heights exclude the trailing row gap.

useItemHeights

import { useItemHeights, type UseItemHeightsResult } from 'masonix';

const { measuredHeights, setItemRef } = useItemHeights(120);

Tracks measured item heights with ResizeObserver. MasonryBalanced and MasonryVirtual use this internally. setItemRef(node, index) is stable and stores border-box heights in a Map<number, number>. Repeated unchanged measurements preserve the map identity.

Pass active measurement identities as the optional second argument when a custom integration continuously replaces items. Measurements outside that set are released instead of remaining cached for the lifetime of the component.

useScroller

import { useScroller, type ScrollerState } from 'masonix/virtual';

const { scrollTop, viewportHeight, scrollVelocity } = useScroller(
  scrollContainerRef,
  12,
);

Tracks scroll position, viewport height, and scroll velocity for either the window or a custom scroll container. The second argument is the sampling FPS and defaults to 12. Custom container height changes are tracked with ResizeObserver. Pass false as the optional third argument when velocity is not consumed; this skips the velocity-settle notification after scrolling.

useScrollToIndex

import {
  useScrollToIndex,
  type UseScrollToIndexOptions,
} from 'masonix/virtual';

const handle = useScrollToIndex({
  positioner,
  containerRef,
  getScrollContainer,
  viewportHeight,
});

Builds a MasonryVirtualHandle with scrollToIndex(), scrollToOffset(), and scrollBy() from positioned items and scroll container state. MasonryVirtual exposes the result through scrollRef; most apps should use that component prop instead of calling this hook directly.

Recommendation

Prefer component props first. Reach for hooks only when the component API cannot represent the integration you are building.