Skip to content
Super simple virtualized list React component
Branch: master
Clone or download
Latest commit 5380e8b Apr 19, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo Support for React 16. Apr 15, 2018
lib [fix] Rebuilds lib Feb 6, 2018
src check for undefined state before comparison Nov 29, 2017
.babelrc Major refactor into HOC Feb 11, 2017
.gitignore Initial commit May 24, 2015
.travis.yml Major refactor into HOC Feb 11, 2017 Major refactor into HOC Feb 11, 2017 Update Apr 19, 2018 Major refactor into HOC Feb 11, 2017 Major refactor into HOC Feb 11, 2017
jsconfig.json Major refactor into HOC Feb 11, 2017
package.json Bump minor version Apr 18, 2018

react-virtual-list Build Status npm bundle size (minified + gzip)

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
  • 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.


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


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

> npm install react-virtual-list --save


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 = ({
}) => (
  <ul style={}>
    { => (
      <li key={`item_${}`} style={{height: itemHeight}}>
        Lorem ipsum dolor sit amet

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.



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);
Name Type Default Description
container DOM Element window Scrollable element that contains the list. Use this if you have a list inside an element with overflow: scroll.
initialState object - An object with firstItemIndex and lastItemIndex properties, which represent array indexes of items (see below). These are used to calculate the visible items before the component is mounted. Useful for server-side rendering.


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

Name Type Default Description
items Array - Full array of list items. Only the visible subset of these will be rendered.
itemHeight Number - Height in pixels of a single item. You must have a CSS rule that sets the height of each list item to this value.
itemBuffer Number 0 Number of items that should be rendered before and after the visible viewport. Try using this if you have a complex list that suffers from a bit of lag when scrolling.


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:

Name Description
props Includes all properties passed to MyVirtualList
state Includes firstItemIndex and lastItemIndex; array indexes of the visible bounds of items

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.


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

You can’t perform that action at this time.