Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/clauderic/virtualized-list
A tiny, Vanilla JS, virtualization library
https://github.com/clauderic/virtualized-list
front-end javascript vanilla virtual-scroll virtualization windowing
Last synced: about 2 months ago
JSON representation
A tiny, Vanilla JS, virtualization library
- Host: GitHub
- URL: https://github.com/clauderic/virtualized-list
- Owner: clauderic
- License: mit
- Created: 2017-01-31T21:07:03.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-10-05T15:24:48.000Z (almost 2 years ago)
- Last Synced: 2024-04-14T15:49:50.978Z (5 months ago)
- Topics: front-end, javascript, vanilla, virtual-scroll, virtualization, windowing
- Language: JavaScript
- Homepage:
- Size: 1 MB
- Stars: 157
- Watchers: 3
- Forks: 25
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# virtualized-list
> A tiny vanilla virtualization library, with DOM diffing
[![npm package][npm-badge]][npm]
[](https://travis-ci.org/clauderic/virtualized-list)
[](https://codecov.io/gh/clauderic/virtualized-list)
Getting Started
------------
Using [npm](https://www.npmjs.com/):
```
npm install virtualized-list --save
```
ES6, CommonJS, and UMD builds are available with each distribution. For example:
```js
import VirtualizedList from 'virtualized-list';
```
You can also use a global-friendly UMD build:
```html
var VirtualizedList = window.VirtualizedList.default;
...
```
Usage
------------
### Basic example
```js
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
```js
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](https://github.com/clauderic/virtualized-list/issues) 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.
[npm-badge]: https://img.shields.io/npm/v/virtualized-list.svg
[npm]: https://www.npmjs.org/package/virtualized-list