Virtual Props

MasonryVirtual accepts all Common Props and all Balanced Props, plus these virtual props.

Prop	Type	Default	Notes
`overscanBy`	`number`	`2`	Extra viewport heights rendered above and below the visible range.
`scrollContainer`	`RefObject<HTMLElement \| null>`	`window`	Custom scroll container for panel-based feeds.
`totalItems`	`number`	`items.length`	Total count for accessibility metadata when not every item is loaded.
`initialScrollIndex`	`number \| { index: number; align?: MasonryScrollAlign }`	-	Initial item position, applied once when the item is available.
`scrollRef`	`Ref<MasonryVirtualHandle>`	-	Imperative scroll handle.
`onRangeChange`	`(startIndex: number, stopIndex: number) => void`	-	Called for the initial non-empty range and later range changes.
`onEndReached`	`(info: MasonryVirtualRange) => void`	-	Called when the rendered range reaches the end threshold.
`endReachedThreshold`	`number`	`0`	Remaining loaded item count before `onEndReached` fires.
`scrollSeek`	`{ velocityThreshold?, placeholder? }`	-	Renders placeholders during fast scrolling.

Range type

interface MasonryVirtualRange {
  startIndex: number;
  stopIndex: number;
  itemCount: number;
  totalItems: number;
}

Scroll handle

interface MasonryVirtualHandle {
  scrollToIndex(
    index: number,
    options?: {
      align?: 'start' | 'center' | 'end' | 'auto';
      smooth?: boolean;
    },
  ): void;
  scrollToOffset(offset: number, options?: { smooth?: boolean }): void;
  scrollBy(delta: number, options?: { smooth?: boolean }): void;
}

scrollToIndex() defaults to align: 'start'. With align: 'auto', a fully visible item stays in place; an item outside the viewport is revealed using the nearest edge. Offset methods normalize negative destinations to zero and ignore non-finite values. Smooth scrolling respects the user's reduced-motion preference.

Scroll seek

<MasonryVirtual
  items={items}
  scrollSeek={{
    velocityThreshold: 1200,
    placeholder: FeedSkeleton,
  }}
  render={({ data }) => <FeedCard item={data} />}
/>

When velocityThreshold is omitted, Masonix uses 1200 px/s.

Negative and non-finite overscan, threshold, count, and velocity values are normalized to safe defaults. totalItems is never allowed below items.length.

Range type

Scroll handle

Scroll seek

On this page