📦 Installation

``bash
npm install react-simple-virtualize


or

`jsx
import React from 'react';
import { useVirtualize } from 'react-simple-virtualize';

const MyLargeList = () => {
// 1. Setup your data
const items = Array.from({ length: 10000 }, (_, i) => Item ${i + 1});

// 2. Initialize the hook
const {
virtualItems,
totalHeight,
scrollRef,
onScroll
} = useVirtualize({
itemCount: items.length,
itemHeight: 50,
overscan: 5,
});

return (
// Outer Container: Needs a size (fixed or flex) & overflow-y: auto
ref={scrollRef}
onScroll={onScroll}
style={{
height: '500px', // Or '100%', 'flex: 1'
overflowY: 'auto',
position: 'relative',
border: '1px solid #ccc'
}}
>
{/ Inner Container: Sets the scrollable height /}


export default MyLargeList;
`

⚙️ API Reference

| Prop | Type | Default | Description |
|---|---|---|---|
| itemCount | number | Required | Total number of items in the list. |
| itemHeight | number | Required | Estimated height of an item. Used for initial rendering and unmeasured items. |
| overscan | number | 3 | Number of extra items to render outside the visible viewport. |
| containerHeight | number | undefined | Optional fixed height. If omitted, the hook uses ResizeObserver on scrollRef to measure it automatically. |

$3

| Value | Type | Description |
|---|---|---|
| virtualItems | VirtualItem[] | Array of items to be rendered in the current viewport. |
| totalHeight | number | Total calculated height of the list (apply this to the inner container). |
| scrollRef | RefObject | Ref to be attached to the scrollable container element (for auto-sizing). |
| onScroll | function | Scroll handler to be attached to the scrollable container. |

#### VirtualItem Interface
`ts
interface VirtualItem {
index: number;
offsetTop: number;
measureRef: (el: HTMLElement | null) => void; // Must be attached to the rendered element
}
`

Migration from v1 to v2

v2 introduces support for Dynamic Heights. This is a breaking change.

Changes:
- You must now attach the measureRef to your rendered element.
- itemHeight prop is now used as an estimate for unrendered items.

`jsx
// v1 (Old)


// v2 (New)