virtualized-list
A tiny vanilla virtualization library, with DOM diffing
Getting Started
Using npm:
npm install virtualized-list --save
ES6, CommonJS, and UMD builds are available with each distribution. For example:
import VirtualizedList from 'virtualized-list';You can also use a global-friendly UMD build:
<script src="virtualized-list/umd/virtualized-list.js"></script>
<script>
var VirtualizedList = window.VirtualizedList.default;
...
</script>Usage
Basic example
const rows = ['a', 'b', 'c', 'd'];
const virtualizedList = new VirtualizedList(container, {
height: 500, // The height of the container
rowCount: rows.length,
renderRow: index => {
const element = document.createElement('div');
element.innerHTML = rows[index];
return element;
},
rowHeight: 150,
});Advanced example
const rows = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const rowHeights = [150, 120, 100, 80, 50, 35, 200, 500, 50, 300];
const virtualizedList = new VirtualizedList(container, {
height: 400,
rowCount: rows.length,
renderRow: (index) => {
const element = document.createElement('div');
element.innerHTML = row;
return element;
},
rowHeight: index => rowHeights[index],
estimatedRowHeight: 155,
overscanCount: 5, // Number of rows to render above/below the visible rows.
initialScrollIndex: 8,
onMount: () => {
// Programatically scroll to item index #3 after 2 seconds
setTimeout(() =>
virtualizedList.scrollToIndex(3)
, 2000);
}
});Options
| Property | Type | Required? | Description |
|---|---|---|---|
| height | Number | โ | Height of List. This property will determine the number of rendered vs virtualized items |
| rowCount | Number | โ | The number of rows you want to render |
| renderRow | Function | โ | Responsible for rendering an item given it's index: ({index: number, style: Object}): HTMLElement. The returned element must handle key and style. |
| rowHeight | Number, Array or Function | โ | Either a fixed height, an array containing the heights of all the items in your list, or a function that returns the height of an item given its index: (index: number): number |
| initialScrollTop | Number | The initial scrollTop value (optional) | |
| initialIndex | Number | Initial item index to scroll to (by forcefully scrolling if necessary) | |
| overscanCount | Number | Number of extra buffer items to render above/below the visible items. Tweaking this can help reduce scroll flickering on certain browsers/devices. Defaults to 3 |
|
| estimatedRowHeight | Number | Used to estimate the total size of the list before all of its items have actually been measured. The estimated total height is progressively adjusted as items are rendered. | |
| onMount | Function | Callback invoked once the virtual list has mounted. | |
| onScroll | Function | Callback invoked onScroll. function (scrollTop, event) |
|
| onRowsRendered | Function | Callback invoked with information about the range of rows just rendered |
Public Instance Methods
scrollToIndex (index: number, alignment: 'start' | 'center' | 'end')
This method scrolls to the specified index. The alignment param controls the alignment scrolled-to-rows. Use "start" to always align rows to the top of the list and "end" to align them bottom. Use "center" to align them in the middle of container.
setRowCount (count: number)
This method updates the total number of rows (rowCount) and will force the list to re-render.
Reporting Issues
Found an issue? Please report it along with any relevant details to reproduce it.
Contributions
Feature requests / pull requests are welcome, though please take a moment to make sure your contributions fits within the scope of the project.
License
virtualized-list is available under the MIT License.