react-dynamic-virtual-list

React virtual list component that aims to be the most flexible and performant.

Features

Super simple setup.
Just over 2 KB Gzipped.
Server side render support.
Supports variable element heights.
Supports a grid layouts with flexbox.
Automatically detects element heights.
Renders with requestAnimationFrame for good scroll performance.
Multiple lifecycle events and hooks.
Typescript, Babel and ES5 support.

Installation

npm i react-dynamic-virtual-list

Using in Typescript/Babel project:

import { DVL } from "react-dynamic-virtual-list";

Using in Node:

const DVL = require("react-dynamic-virtual-list").DVL;

To use directly in the browser, drop the tag below into your <head>.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/react-dvl.min.js"></script>

Quick Start

import { DVL } from "react-dynamic-virtual-list";
import * as React from "react";

class App extends React.Component<any, any> {
    render() {
        return <DVL
            onRender={item => <div>{item.name}</div>}
            items={[{name: "Billy"}, {name: "Joel"}]}
            windowContainer={true}
        />
    }
}

API

The Dynamic Virtual List will render your items 100 at a time onto the dom and measure their height using .clientHeight, then use that cached value to render the actual virtual list. The virtual list will grow in size appropriately as it completes measuring each block.

Callbacks can be used to hide the element while it's doing this, or the behavior can be avoided entirely by passing different values into the calculateHeight prop.

Grid layouts are supported provided each element is a fixed width.

Props

* Required

*onRender: `(item: any, index: number, columns?: number) => JSX.Element`

Function to use to render each element, must return a JSX Element. If using a grid layout make sure you set fixed widths to your elements. DO NOT use margins, if you need spacing between the elements create an inner element that contains the actual content, creating the margins with an outer div.

If using grid layout, the number of columns currently being displayed is passed into this prop as well. Keep in mind the initial render won't provide a columns argument so even with a grid layout you should set up your render prop to handle undefined column values.

*items: `any[]`

Array of items to render into the list.

calculateHeight: `number | (container: HTMLDivElement, item: any, index: number) => number`

If this prop is unused, the library will render every element onto the page to discover it's height with .clientHeight, then display it in the virtual list, 100 items at a time. You can change this behavior completely by either passing in a function to use for calculating heights or a number that will be used as a fixed height for all elements.

Passing in a fixed number is by far the most performant option while the function is a good second choice.

IMPORTANT! The library makes zero attempts to resolve height conflicts. If you give a fixed height to the calculateHeight prop and the elements aren't actually fixed to that height, you're gonna have a bad time.

windowContainer: `boolean`

Pass "true" to use the window as the scroll container.

buffer: `number`

Default is 5, number of rows to render below and above the visual area.

containerRef: (ref: `HTMLDviElement`) => void

The ref of the container DIV generated by the library to contain the inner container div and it's list.

containerStyle: `React.CSSProperties`

Pass through styles to the container DIV. If you aren't using the window as a container then set a fixed height and overflowY: "scroll" here.

containerClass: `string`

Pass through classes to the container DIV.

innerContainerStyle: `React.CSSProperties`

Pass through styles to the inner container DIV. This div holds the list of rendered elements. If you plan to do Flexbox this is the place to put your styles. paddingTop and height styles will be ignored/overwritten.

innerContainerClass: `string`

Pass through classes to the inner container DIV that holds the list elements.

doUpdate: `(calcVisible: (scrollTop?: number, containerHeight?: number) => void) => void`

By default the library attaches the method to calculate the visible space to the scroll event and renders onRequestAnimationFrame. You can disable and override this behavior by using this prop, the only argument is the method that calculates what should be visible on the screen. You can even pass in manually generated height and scrollTop values into the method. When you use this prop the library will only update it's visible area when the provided function is called or on window resize.

If no scrollTop or containerHeight arguments are passed in the library will fall back to it's default behavior, using the window or container to measure what should show up.

gridItemWidth: `number`

Leave blank if you're doing one item per row. If you're doing a grid layout then pass in the fixed width of your grid items here.

onResizeStart: `(doResize: () => void) => void`

On the first render and each time the screen resizes the height of every element is checked and the list is re rendered from scratch. This prop is called just after the resize has triggered. The callback method triggers the actual resize methods, so you can decide when the layout should be recalculated, useful for transitions and the like.

onResizeFinish: `(scrollHeight: number, columns: number) => void`

Once the resize is done being calculated this prop will be called. The total height of all elements and the number of columns calculated is also passed in as the single argument.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

only-cliches / react-dynamic-virtual-list Goto Github PK