react-virtual-list

Super simple virtualized list higher-order component for React version ^15.0.0 || ^16.0.0.

Check out the demo here

react-virtual-list allows you to display a large list of fixed-height items, while only rendering the items visible on the screen. This allows a large list to be rendered with much fewer DOM elements.

Some other benefits:

• One dependency (and it's prop-types)
• Small!
• Performant - demo page almost always stays over 60fps http://i.imgur.com/CHVCK9x.png
• Keeps your components separate - as a higher-order component
• Gives you control - doesn't force any particular markup, but gives you the necessary styles and data to use.

Legacy

If you're looking for documentation on version 1, supporting React ~0.13.x, it's here.

Installation

You can use npm to install react-virtual-list.

> npm install react-virtual-list --save

Usage

The ./lib/VirtualList.js module exports a single, ES5-compatible, CommonJS-accessible, component factory.

import VirtualList from 'react-virtual-list';

Your inner list component uses the virtual property to render the visible items, and set a style to set the overall list height and padding.

const MyList = ({
  virtual,
  itemHeight,
}) => (
  <ul style={virtual.style}>
    {virtual.items.map(item => (
      <li key={`item_${item.id}`} style={{height: itemHeight}}>
        Lorem ipsum dolor sit amet
      </li>
    ))}
  </ul>
);

Note: You should set keys on your list items.

Create the virtualized component.

const MyVirtualList = VirtualList()(MyList);

Write the JSX for the virtualized component with the necessary properties.

<MyVirtualList
  items={myBigListOfItems}
  itemHeight={100}
/>

Options

Options are used before the virtualized component can be created. This means that if you need to change an option after the initial render, you will need to recreate the virtualized component.

const options = {
  container: this.refs.container, // use this scrollable element as a container
  initialState: {
    firstItemIndex: 0, // show first ten items
    lastItemIndex: 9,  // during initial render
  },
};

const MyVirtualList = VirtualList(options)(MyList);

Properties

These properties and any others set on your virtual component, such as className, will be passed down to the inner component.

Mapping

VirtualList allows a second, optional, parameter, named mapVirtualToProps, which functions similarly to Redux's mapStateToProps. This function can be provided to change the properties passed to MyList. Its arguments are:

The default mapVirtualToProps can be found here.

Example Usage

Check out demo/src/app.js and demo/src/ConfigurableExample.js for the example used in the demo.

Tests

Use npm test to run the tests using Jest. Not everything is currently tested yet!