react-io-virtual-list
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

react-io-virtual-list

A react virtual scrolling component implemented by splitting the items into a binary tree where the visibility of each node is tracked using an intersection observer. A scroll event based observer is also available as a fallback or if preferred.

Due to the way the component works, some extra wrapping elements are added and list elements won't be rendered as siblings. This limits some of the styling that can be done, for example spacing the items with a grid or flexbox.

Install

# Yarn
yarn add react-io-virtual-list

# NPM
npm install --save react-io-virtual-list

Features

  • Very simple with almost zero DOM querying
  • Supports vertical and horizontal lists
  • Dynamic sized items support without special configuration
  • Ability to scroll to item
  • Performant
  • Written in TypeScript

Usage

import * as React from "react";
import { VirtualList } from "react-io-virtual-list";

export const MyList = () => {
  const ref = React.useRef<HTMLDivElement | null>(null);
  const heights = Array.from({ length: 100 }, () =>
    Math.floor(Math.random() * 80 + 20)
  );

  const Item = ({ index }: { index: number }) => {
    return (
      <div
        style={{
          height: `${heights[index]}px`,
          border: "1px solid black",
        }}
      >
        {`Item ${index}`}
      </div>
    );
  };

  return (
    <div
      ref={ref}
      style={{ overflow: "scroll", height: "200px", width: "200px" }}
    >
      <VirtualList
        nrItems={100}
        estimatedSize={60}
        scrollContainerRef={ref}
        renderItem={Item}
      />
    </div>
  );
};

API

Name Type Default Description
nrItems number required Number of items in the list
estimatedSize number required The estimated size for each item in pixels. Will be used until the item is rendered at least once.
scrollContainerRef React.RefObject required A reference to the container the scroll overflows
renderItem React.ElementType required The item component to render. Expected sizes are provided in case a placeholder needs to be rendered, for example when fetching data.
renderPlaceholder React.ElementType <div /> An optional placeholder component to be used to render spacers in the list. A spacer might substitute one or more items.
nrItemsOverscan number 0 The number of extra items to render above or below the visible area calculated based on the estimated size.
direction "vertical" | "horizontal" "vertical" The direction of the list
sizeMap SizeMap {} Optionally pass in an initial size map if known, for example gotten through `getSizeMap``. Useful for exact scroll restoration where you would, for example, save the size map on unmount and pass it in again when remounting
observerType "intersectionObserver" | "scrollEvent" "intersectionObserver" Specify the type of observer to be used

intersectionObserver - uses an intersection observer to detect when items are scrolled into view. This is generally a more performant option when it comes to framerate but there might be more spacers visible due to the very async nature of intersection observers

scrollEvent - sets up a scroll event listener on the scroll node and reads the bounding rect on observed elements on scroll to calculate intersections.
handleRef React.RefObject undefined A imperitive handle ref to get access to methods on the VirtualList component

scrollTo - scroll to an index in the list

getSizeMap - get the current size map to for example persist it
initialInView number 0 If known the number of items that are initially in view. This allows for "synchronous" render of initial items without first rendering a placeholder

Package Sidebar

Install

npm i react-io-virtual-list

Weekly Downloads

1

Version

1.0.1

License

ISC

Unpacked Size

127 kB

Total Files

17

Last publish

Collaborators

  • c99pjn