ReactList
A versatile infinite scroll React component.Install
bower install react-list
# or
npm install react-list
ReactList depends on React.
Examples
Check out the example page and the the example page source for examples of different configurations.Here's another simple example to get you started.
import loadAccount from 'my-account-loader';
import React from 'react';
import ReactList from 'react-list';
class MyComponent extends React.Component {
state = {
accounts: []
};
componentWillMount() {
loadAccounts(::this.handleAccounts);
}
handleAccounts(accounts) {
this.setState({accounts});
}
renderItem(index, key) {
return <div key={key}>{this.state.accounts[index].name}</div>;
}
render() {
return (
<div>
<h1>Accounts</h1>
<div style={{overflow: 'auto', maxHeight: 400}}>
<ReactList
itemRenderer={::this.renderItem}
length={this.state.accounts.length}
type='uniform'
/>
</div>
</div>
);
}
}
Props
axis (defaults to y
)
The axis that this list scrolls on.initialIndex
An index to scroll to after mounting.itemRenderer(index, key)
A function that receives an index and a key and returns the content to be rendered for the item at that index.itemsRenderer(items, ref)
A function that receives the rendered items and a ref. By default this element is just a<div>
. Generally it only needs to be overridden for use in a
<table>
or other special case. NOTE: You must set ref={ref} on the component
that contains the items
so the correct item sizing calculations can be made.itemSizeEstimator(index, cache)
A function that receives an item index and the cached known item sizes and returns an estimated size (height for y-axis lists and width for x-axis lists) of that item at that index. This prop is only used when the proptype
is set
to variable
and itemSizeGetter
is not defined. Use this property when you
can't know the exact size of an item before rendering it, but want it to take up
space in the list regardless.itemSizeGetter(index)
A function that receives an item index and returns the size (height for y-axis lists and width for x-axis lists) of that item at that index. This prop is only used when the proptype
is set to variable
.length (defaults to 0
)
The number of items in the list.minSize (defaults to 1
)
The minimum number of items to render at any given time. This can be used to
render some amount of items initially when rendering HTML on the server.pageSize (defaults to 10
)
The number of items to batch up for new renders. Does not apply to 'uniform'
lists as the optimal number of items is calculated automatically.scrollParentGetter (defaults to finding the nearest scrollable parent)
A function that returns a DOM Element or Window that will be treated as the scrolling container for the list. In most cases this does not need to be set for the list to work as intended. It is exposed as a prop for more complicated uses where the scrolling container may not initially have an overflow property that enables scrolling.scrollParentViewportSizeGetter (defaults to scrollParent's viewport size)
A function that returns the size of the scrollParent's viewport. Provide this prop if you can efficiently determine your scrollParent's viewport size as it can improve performance.threshold (defaults to 100
)
The number of pixels to buffer at the beginning and end of the rendered list
items.type (one of simple
, variable
, or uniform
, defaults to simple
)
simple
This type is...simple. It will not cache item sizes or remove items
variable
This type is preferred when the sizes of the items in the list
itemSizeGetter
when possible so the entire length of the
list can be established beforehand. Otherwise, the item sizes will be cached
as they are rendered so that items that are above the viewport can be removed as
the list is scrolled.uniform
This type is preferred when you can guarantee all of your
useStaticSize (defaults to false
)
Set to true
if the item size will never change (as a result of responsive
layout changing or otherwise). This prop is only used when the prop type
is
set to uniform
. This is an opt-in optimization that will cause the very first
element's size to be used for all elements for the duration of the component's
life.useTranslate3d (defaults to false
)
A boolean to determine whether the translate3d
CSS property should be used for
positioning instead of the default translate
. This can help performance on
mobile devices, but is supported by fewer browsers.Methods
scrollTo(index)
Put the element atindex
at the top of the viewport. Note that if you aren't
using type='uniform'
or an itemSizeGetter
, you will only be able to scroll
to an element that has already been rendered.scrollAround(index)
Scroll the viewport so that the element atindex
is visible, but not
necessarily at the top. The scrollTo
note above also applies to this method.getVisibleRange() => [firstIndex, lastIndex]
Return the indices of the first and last items that are at all visible in the
viewport.FAQ
What is "ReactList failed to reach a stable state."?
This happens when specifying theuniform
type without actually providing
uniform size elements. The component attempts to draw only the minimum necessary
elements at one time and that minimum element calculation is based off the first
element in the list. When the first element does not match the other elements,
the calculation will be wrong and the component will never be able to fully
resolve the ideal necessary elements.Why doesn't it work with margins?
The calculations to figure out element positioning and size get significantly more complicated with margins, so they are not supported. Use a transparent border or padding or an element with nested elements to achieve the desired spacing.Why is there no onScroll event handler?
If you need an onScroll handler, just add the handler to the div wrapping your ReactList component:<div style={{height: 300, overflow: 'auto'}} onScroll={this.handleScroll}>
<ReactList ... />
</div>
Development
open docs/index.html
make