Warper

The useVirtualizer hook is the recommended way to implement virtualization when you need fine-grained control over the rendering logic and container structure.

It returns:

• scrollElementRef: A ref to be attached to the scrollable container.
• range: An object containing items (the indices of visible items), offsets (the Y positions for each item), and sizes (the height of each item).
• totalHeight: The calculated total height of the entire list to ensure correct scrollbar behavior.

Required options:

• itemCount: Total number of items in the list.
• estimateSize: A function that returns the estimated height of an item.
• overscan: (Optional) Number of items to render outside the visible area to reduce flickering during scrolling.

import { useVirtualizer } from '@itsmeadarsh/warper';

function MyList() {
  const { scrollElementRef, range, totalHeight } = useVirtualizer({
    itemCount: 1_000_000,
    estimateSize: () => 50,
    overscan: 5,
  });

  return (
    <div ref={scrollElementRef} style={{ height: 500, overflow: 'auto' }}>
      <div style={{ height: totalHeight, position: 'relative' }}>
        {range.items.map((index, i) => (
          <div
            key={index}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${range.offsets[i]}px)`,
              height: range.sizes[i],
              width: '100%',
            }}
          >
            Row {index}
          </div
        ))}
      </div
    </div>
  );
}

The useVirtualizer hook is the recommended way to implement virtualization. It provides a scrollElementRef to attach to your container, a range object containing visible item data, and utility methods for scrolling.

Hook Options

• itemCount (required): Total number of items.
• estimateSize (required): Function returning item height: (index: number) => number.
• overscan (default: 5): Extra items to render above/below the visible area.
• horizontal (default: false): Enables horizontal scroll mode.
• height (default: '100%'): Container height.

Return Values

• scrollElementRef: Ref to attach to the scroll container.
• range: An object of type VirtualRange containing current visible data.
• totalHeight: Total scrollable height.
• isLoading: Boolean indicating WASM loading state.
• error: Error object if initialization failed.
• scrollToIndex: Function to scroll to a specific index: (index, behavior?) => void.
• scrollToOffset: Function to scroll to a pixel offset: (offset, behavior?) => void.

import { useVirtualizer } from '@itsmeadarsh/warper';

function MyList() {
  const { scrollElementRef, range, totalHeight } = useVirtualizer({
    itemCount: 1_000_000,
    estimateSize: () => 50,
    overscan: 5,
  });

  return (
    <div ref={scrollElementRef} style={{ height: 500, overflow: 'auto' }}>
      <div style={{ height: totalHeight, position: 'relative' }}>
        {range.items.map((index, i) => (
          <div
            key={index}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${range.offsets[i]}px)`,
              height: range.sizes[i],
              width: '100%',
            }}
          >
            Row {index}
          </div>
        ))}
      </div>
    </div>
  );
}

The WarperComponent is a ready-to-use component that abstracts the virtualization logic. It accepts a render function as children.

Props

• itemCount (required): Total number of items.
• estimateSize (required): Function returning item height.
• children (required): A function (index: number) => React.ReactNode to render each item.
• overscan (optional): Extra items to render.
• height (optional): Container height.
• horizontal (optional): Enables horizontal mode.
• className (optional): CSS class name.
• style (optional): Inline styles.
• onRendered (optional): Callback when items are rendered.
• loadingPlaceholder (optional): Component to show while loading.
• errorPlaceholder (optional): Function (error: Error) => React.ReactNode to handle errors.

import { WarperComponent } from '@itsmeadarsh/warper';

function MyList() {
  return (
    <WarperComponent
      itemCount={1_000_000}
      estimateSize={() => 50}
      height={500}
      overscan={5}
    >
      {(index) => (
        <div style={{ padding: 16 }}>
          Row {index}
        </div>
      )}
    </WarperComponent>
  );
}