search

gnir-work / react-window-dynamic-list

A naive approach to virtualizing a dynamically sized list
49 stars 9 forks source link

readme

react-window-dynamic-list

Made with the awesome create-react-library

NPM NPM Installs JavaScript Style Guide

How is this different from react-window?

This library comes to partly solve the case of rendering dynamically sized items with react-window, for more information about the issue please read this thread. Before you overjoy please read the limitations of this approach down bellow :sleepy:

Demo

👉 check out dynamic list in action

:pencil2: Play with the demo in sandbox

Install

npm install --save react-window-dynamic-list

Usage

Usage Preview

Yep. its that simple :satisfied:

API

The API is the same as VariableSizeList with some small changes and additions.

Changes

  1. Instead of itemCount you must pass data (read more)
  2. We handle itemSize and estimatedItemSize for you :sunglasses:

Additions

Property Type Required? Default Description
data Object[] ✓ All of the data that will be displayed in the list.
Each object must contain an unique id field.
For example: [{id: 1, ...}, {id: 2, ....}]
cache Object ✓ The cache object which the list will use for caching the calculated sizes.
Check the example for how to create it.
lazyMeasurement boolean true Whether the application should fill the cache in the background.
Please note: After each cache clear the application will restart the lazy cache filling (For example after adding or removing an item)
For more information read the caching section.
recalculateItemsOnResize Object { width: false, height: false } Whether the list should recalculate the items size if its own size has changed. This value should not change from its initial one.
Currently the feature is supported but far from perfect, therefore it is disabled by default.
measurementContainerElement Function ({style, children}) => ReactNode A custom container element in which the elements will be rendered for measuring. Especially useful for changing the scrollbar width.
You must pass the style prop to your element.
debug boolean false Whether the measurement layer should be visible, useful for debugging a custom measurementContainerElement

Implementations details

TL;DR:

Just in time measurement with caching in the background.

Details:

The algorithm is divided into two main concepts:

Just in time measurements:

We measure each item in the list by temporary rendering it with react-dom in a different application. For more information please read this great article.

Caching:

In order for just in time measurements to be effective we need to cache the measurements. Currently there are two caching modes:

  1. Cache only the items that were rendered
  2. On top of caching the rendered items a background task will measure each element and fill the cache. This is the default behavior as it gives a significant performance boost, especially in case of manipulating the data before scrolling through it. In exchange there is a very mild slow down in overall performance in the first couple of seconds and after each change to the size of the list.
    :warning: Please note: the lazy cache filling will be triggered in case you call resetAfterIndex function of VariableSizeList.

:warning: Requirements and Limitations :warning:

  1. Your data doesn't change its size.

    • Your items size must be determined on mount (No ajax or images).

  2. Currently only supports vertical layout. (didn't have time to implement support for horizontal).

  3. All of the styling regarding the items must be inline or not affected by location in the DOM.

  4. Changes to the list's scrollbar, especially the width, should also effect the measurement container div. Since we pre render the items in order to measure them the size of the scrollbar is important in the pre rendered item as well. This can be achieved in the following ways:

    1. Make sure all of the scrollbars in the application are styled the same
    2. Pass a custom measurement container element via the measurementContainerElement prop.

License

MIT © gnir-work