react-window

React components for efficiently rendering large lists and tabular data

If you like this project, 🎉 become a sponsor or ☕ buy me a coffee

React window works by only rendering part of a large data set (just enough to fill the viewport). This helps address some common performance bottlenecks:

1. It reduces the amount of work (and time) required to render the initial view and to process updates.
2. It reduces the memory footprint by avoiding over-allocation of DOM nodes.

Sponsors

The following wonderful companies have sponsored react-window:

Learn more about becoming a sponsor!

Install

# Yarn
yarn add react-window

# NPM
npm install --save react-window

Usage

Learn more at react-window.now.sh:

Related libraries

• react-virtualized-auto-sizer: HOC that grows to fit all of the available space and passes the width and height values to its child.
• react-window-infinite-loader: Helps break large data sets down into chunks that can be just-in-time loaded as they are scrolled into view. It can also be used to create infinite loading lists (e.g. Facebook or Twitter).
• react-vtree: Lightweight and flexible solution to render large tree structures (e.g., file system).

Frequently asked questions

How is react-window different from react-virtualized?

I wrote react-virtualized several years ago. At the time, I was new to both React and the concept of windowing. Because of this, I made a few API decisions that I later came to regret. One of these was adding too many non-essential features and components. Once you add something to an open source project, removing it is pretty painful for users.

react-window is a complete rewrite of react-virtualized. I didn't try to solve as many problems or support as many use cases. Instead I focused on making the package smaller¹ and faster. I also put a lot of thought into making the API (and documentation) as beginner-friendly as possible (with the caveat that windowing is still kind of an advanced use case).

If react-window provides the functionality your project needs, I would strongly recommend using it instead of react-virtualized. However if you need features that only react-virtualized provides, you have two options:

1. Use react-virtualized. (It's still widely used by a lot of successful projects!)
2. Create a component that decorates one of the react-window primitives and adds the functionality you need. You may even want to release this component to NPM (as its own, standalone package)! 🙂

^{1 - Adding a react-virtualized list to a CRA project increases the (gzipped) build size by ~33.5 KB. Adding a react-window list to a CRA project increases the (gzipped) build size by <2 KB.}

Can a list or a grid fill 100% the width or height of a page?

Yes. I recommend using the react-virtualized-auto-sizer package:

Here's a Code Sandbox demo.

Why is my list blank when I scroll?

If your list looks something like this...

...then you probably forgot to use the style parameter! Libraries like react-window work by absolutely positioning the list items (via an inline style), so don't forget to attach it to the DOM element you render!

Can I lazy load data for my list?

Yes. I recommend using the react-window-infinite-loader package:

Here's a Code Sandbox demo.

Can I attach custom properties or event handlers?

Yes, using the outerElementType prop.

Here's a Code Sandbox demo.

Can I add padding to the top and bottom of a list?

Yes, although it requires a bit of inline styling.

Here's a Code Sandbox demo.

Can I add gutter or padding between items?

Yes, although it requires a bit of inline styling.

Here's a Code Sandbox demo.

Does this library support "sticky" items?

Yes, although it requires a small amount of user code. Here's a Code Sandbox demo.

License

MIT © bvaughn

Changelog

1.8.11

• Dependencies updated to include React 19

1.8.10

• Fix scrollDirection when direction is RTL (#690)

1.8.9

• Readme changes

1.8.8

• 🐛 scrollToItem accounts for scrollbar size in the uncommon case where a List component has scrolling in the non-dominant direction (e.g. a "vertical" layout list also scrolls horizontally).

1.8.7

• ✨ Updated peer dependencies to include React v18.

1.8.6

• ✨ Updated peer dependencies to include React v17.

1.8.5

• ✨ Added UMD (dev and prod) build - (emmanueltouzery - #281)

1.8.4

• 🐛 Fixed size list and grid components now accurately report visibleStopIndex in onItemsRendered. (Previously this value was incorrectly reported as one index higher.) - (justingrant - #274)
• 🐛 Fixed size list and grid components scrollToItem "center" mode when the item being scrolled to is near the viewport edge. - (justingrant - #274)

1.8.3

• 🐛 Edge case bug-fix for scrollToItem when scrollbars are present (MarkFalconbridge - #267)
• 🐛 Fixed RTL scroll offsets for non-Chromium Edge (MarkFalconbridge - #268)
• 🐛 Flow types improved (TrySound - #260)

1.8.2

• ✨ Deprecated grid props overscanColumnsCount and overscanRowsCount props in favor of more consistently named overscanColumnCount and overscanRowCount. (nihgwu - #229)
• 🐛 Fixed shaky elastic scroll problems present in iOS Safari. #244
• 🐛 Fixed RTL edge case bugs and broken scroll-to-item behavior. #159
• 🐛 Fixed broken synchronized scrolling for RTL lists/grids. #198

1.8.1

• 🐛 Replaced an incorrect empty-string value for pointer-events with undefined (oliviertassinari - #210)

1.8.0

• 🎉 Added new "smart" align option for grid and list scroll-to-item methods (gaearon - #209)

1.7.2

• 🐛 Add guards to avoid invalid scroll offsets when scrollTo() is called with a negative offset or when scrollToItem is called with invalid indices (negative or too large).

1.7.1

• 🐛 Fix SSR regression introduced in 1.7.0 - (Betree - #185)

1.7.0

• 🎉 Grid scrollToItem supports optional rowIndex and columnIndex params (jgoz - #174)
• DEV mode checks for WeakSet support before using it to avoid requiring a polyfill for IE11 - (jgoz - #167)

1.6.2

• 🐛 Bugfix for RTL when scrolling back towards the beginning (right) of the list.

1.6.1

• 🐛 Bugfix to account for differences between Chrome and non-Chrome browsers with regard to RTL and "scroll" events.

1.6.0

• 🎉 RTL support added for lists and grids. Special thanks to davidgarsan for his support. - #156
• 🐛 Grid scrollToItem methods take scrollbar size into account when aligning items - #153

1.5.2

• 🐛 Edge case bug fix for VariableSizeList and VariableSizeGrid when the number of items decreases while a scroll is in progress. - (iamsolankiamit - #138)

1.5.1

• 🐛 Updated getDerivedState Flow annotations to address a warning in a newer version of Flow.

1.5.0

• 🎉 Added advanced memoization helpers methods areEqual and shouldComponentUpdate for item renderers. - #114

1.4.0

• 🎉 List and Grid components now "overscan" (pre-render) in both directions when scrolling is not active. When scrolling is in progress, cells are only pre-rendered in the direction being scrolled. This change has been made in an effort to reduce visible flicker when scrolling starts without adding additional overhead during scroll (which is the most performance sensitive time).
• 🎉 Grid components now support separate overscanColumnsCount and overscanRowsCount props. Legacy overscanCount prop will continue to work, but with a deprecation warning in DEV mode.
• 🐛 Replaced setTimeout with requestAnimationFrame based timer, to avoid starvation issue for isScrolling reset. - #106
• 🎉 Renamed List and Grid innerTagName and outerTagName props to innerElementType and outerElementType to formalize support for attaching arbitrary props (e.g. test ids) to List and Grid inner and outer DOM elements. Legacy innerTagName and outerTagName props will continue to work, but with a deprecation warning in DEV mode.
• 🐛 List re-renders items if direction prop changes. - #104

1.3.1

• 🎉 Pass itemData value to custom itemKey callbacks when present - #90)

1.3.0

• (Skipped)

1.2.4

• 🐛 Added Flow annotations to memoized methods to avoid a Flow warning for newer versions of Flow

1.2.3

• 🐛 Relaxed children validation checks. They were too strict and didn't support new React APIs like memo.

1.2.2

• 🐛 Improved Flow types for class component item renderers - (nicholas-l - #77)

1.2.1

• 🎉 Improved Flow types to include optional itemData parameter. (TrySound - #66)
• 🐛 VariableSizeList and VariableSizeGrid no longer call size getter functions with invalid index when item count is zero.

1.2.0

• 🎉 Flow types added to NPM package. (TrySound - #40)
• 🎉 Relaxed grid scrollTo method to make scrollLeft and scrollTop params optional (so you can only update one axis if desired). - #63)
• 🐛 Fixed invalid this pointer in VariableSizeGrid that broke the resetAfter* methods - #58)
• Upgraded to babel 7 and used shared runtime helpers to reduce package size slightly. (TrySound - #48)
• Remove overflow:hidden from inner container (souporserious - #56)

1.1.2

• 🐛 Fixed edge case scrollToItem bug that caused lists/grids with very few items to have negative scroll offsets.

1.1.1

• 🐛 FixedSizeGrid and FixedSizeList automatically clear style cache when item size props change.

1.1.0

• 🎉 Use explicit constructor and super to generate cleaner component code. (Andarist - #26)
• 🎉 Add optional shouldForceUpdate param reset-index methods to specify forceUpdate behavior. (nihgwu - #32)

1.0.3

• 🐛 Avoid unnecessary scrollbars for lists (e.g. no horizontal scrollbar for a vertical list) unless content requires them.

1.0.2

• 🎉 Enable Babel annotate-pure-calls option so that classes compiled by "transform-es2015-classes" are annotated with #__PURE__. This enables UglifyJS to remove them if they are not referenced, improving dead code elimination in application code. (Andarist - #20)
• 🎉 Update "rollup-plugin-peer-deps-external" and use new includeDependencies flag so that the "memoize-one" dependency does not get inlined into the Rollup bundle. (Andarist - #19)
• 🎉 Enable Babel "loose" mode to reduce package size (-8%). (Andarist - #18)

1.0.1

Updated README.md file to remove @alpha tag from NPM installation instructions.

1.0.0

Initial release of library. Includes the following components:

• FixedSizeGrid
• FixedSizeList
• VariableSizeGrid
• VariableSizeList