A React hook-based library for efficient grid virtualization
npm install @virtualgrid/lib@virtualgrid/libReact virtualization library for rendering large datasets using CSS Grid.
This package contains the core Virtual Grid hook and utilities. It only renders visible items on screen and automatically adapts to CSS Grid layout changes through ResizeObserver, making it suitable for responsive grids, image galleries, and carousels.
``bash`
npm install @virtualgrid/libor
yarn add @virtualgrid/lib
`tsx
import { useVirtualGrid } from '@virtualgrid/lib'
function Grid() {
const data = Array.from({ length: 10_000 }, (_, i) => ({ id: i, name: Item ${i} }))
const {
items,
styles,
gridRef,
scrollRef,
} = useVirtualGrid({
data,
gap: 20,
padding: [20, 20, 20, 20],
offScreenPages: 1,
})
return (
$3
`ts
import type { VirtualGrid, VirtualGridProps } from '@virtualgrid/lib'function useVirtualGrid(props: VirtualGridProps): VirtualGrid
`
VirtualGridProps-
data: T[] – Items to virtualize (required)
- offScreenPages?: number – Number of pages to render outside the viewport
- padding?: number[] – [top, right, bottom, left] padding; must match your CSS padding
- gap?: number – Gap between grid items; must match your CSS gap
- horizontal?: boolean – Enable horizontal scrolling
VirtualGridCore return shape (simplified):
-
items: T[] – Visible items to render
- styles: React.CSSProperties – Styles to apply to the grid container
- gridRef: React.RefObject
- scrollRef: React.RefObject
- page: number
- pageRange: number[]
- onScrollTo(page: number): void
- Layout fields (scroll sizes, grid dimensions, etc.)For full details, see the exported types:
`ts
import { VirtualGrid, VirtualGridProps, Layout } from '@virtualgrid/lib'
`$3
- Padding-based positioning – Uses dynamic padding instead of absolute positioning to maintain scroll position while letting CSS Grid handle layout.
- Resize-aware – Uses
ResizeObserver to react to container and layout changes.
- Page-based virtualization – Renders only the current and surrounding pages, controlled by offScreenPages.$3
- Not designed for masonry layouts (requires predictable item height).
- Works best when items have uniform sizes.
- CSS
gap and padding must match the values passed to the hook.$3
From the repo root:
`bash
yarn install
yarn dev:lib
`To run tests for this package:
`bash
cd packages/lib
yarn test
``