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:
;Using in Node:
const DVL = DVL;To use directly in the browser, drop the tag below into your <head>.
Quick Start
;; 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
Copyright (c) 2018 Scott Lott
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.