VirtualizedGrid

A virtualized grid component for efficiently rendering large datasets in a grid layout

Storybook @choice-ui/virtualized-grid View Source

Installation

Terminal

pnpm add @choice-ui/virtualized-grid

Import

Component.tsx

import { VirtualizedGrid, useContainerData, useConfigData, useLayoutData, useRenderData, useConstRef, useWindowSize, useElementSize, useWindowScroll, useElementScroll, useElementWindowOffset, useIntersecting, getColumnWidth, getGridRowStart, type ConstRef, type ElementSize, type ElementScroll, type ItemDataProps, type EntryProps, type ConfigDataProps, type ContainerDataProps, type CellProps, type LayoutDataProps, type RenderDataProps, type VirtualizedGridProps, type PooledItem, type ItemPoolOptions, useItemPool } from "@choice-ui/virtualized-grid"

Basic

Basic grid layout with responsive columns.

Note: This component uses window scroll by default. For best testing experience, open in a standalone window.

Demonstrates:

- Basic setup with responsive column calculation - Default overscan behavior (5 rows) - Dynamic item height based on column width

This component uses window scroll. Open in a standalone window for best experience.

List Mode

List mode for single-column vertical layouts.

Demonstrates:

- List mode with single column (`listMode={true}`) - Fixed row height for consistent layout - Horizontal card layout with avatar

This component uses window scroll. Open in a standalone window for best experience.

Performance Optimized

Performance optimized setup with DOM node pooling.

Demonstrates:

- DOM node pooling for memory efficiency - Minimal overscan for better performance - Large dataset handling (10k items)

This component uses window scroll. Open in a standalone window for best experience.

Container Scroll

Container scroll implementation within a ScrollArea.

Demonstrates:

- Custom scroll container setup - Integration with ScrollArea component - Constrained height virtualization

```tsx const scrollRef = useRef<HTMLDivElement>(null) const containerRef = useRef<HTMLDivElement>(null) <ScrollArea> <ScrollArea.Viewport ref={scrollRef}> <ScrollArea.Content ref={containerRef}> <VirtualizedGrid scrollRef={scrollRef} containerRef={containerRef} // ... other props /> </ScrollArea.Content> </ScrollArea.Viewport> </ScrollArea> ```

Error Handling

Error handling and edge cases demonstration.

Demonstrates:

- Custom error boundary fallback - Error recovery mechanisms - Empty state handling

This component uses window scroll. Open in a standalone window for best experience.

Playground

Interactive configuration playground.

Demonstrates:

- Dynamic configuration changes - Real-time performance impact visualization - Different overscan values - Variable item sizes

This component uses window scroll. Open in a standalone window for best experience.

API reference

VirtualizedGrid	Type	Default
className	string \| undefined	-
columnCount	(elementWidth: number, gridGap: number) => number	-
containerRef	RefObject<HTMLElement> \| undefined	-
enablePooling	boolean \| undefined	-
errorFallback	ComponentType<{ error?: Error \| undefined; retry: () => void; }> \| undefined	-
fixedColumnWidth	number \| undefined	-
gridGap	((elementWidth: number, windowHeight: number) => number) \| undefined	-
itemData	(item: P, columnWidth: number) => ItemDataProps	-
itemProps	HTMLAttributes<HTMLDivElement> \| undefined	-
items	P[]	-
listMode	boolean \| undefined	-
maxPoolSize	number \| undefined	-
onError	((error: Error, errorInfo: ErrorInfo) => void) \| undefined	-
overscan	number \| undefined	-
poolSize	number \| undefined	-
renderItem	(item: P, index?: number \| undefined) => ReactNode	-
scrollRef	RefObject<HTMLElement> \| undefined	-
useLayoutData	Type	Default
columnCount	number	-
entries	EntryProps<P>[]	-
gridGap	number	-
overscan	number	-
VirtualizedGridErrorBoundary	Type	Default
fallback	ComponentType<{ error?: Error \| undefined; retry: () => void; }> \| undefined	-
onError	((error: Error, errorInfo: ErrorInfo) => void) \| undefined	-