React VirtualizedItemGrid
VirtualizedItemGrid is a React component for efficiently rendering a large, scrollable list of items in a series of wrapping rows.
It does this by leveraging react-virtualized
to render a virtualized grid of an arbitrary number of rows and a set of columns based on the provided idealItemWidth
and the space available to render said grid.
One could render 1,000,000 items using VirtualizedItemGrid, but only the ones visibly on-screen will be rendered, leading to increased performance.
Demo
http://engineering.nike.com/react-virtualized-item-grid/
Installation
npm install react-virtualized-item-grid
Usage
Functional stateless component:
;; { return <div>itemname</div>;} { return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard />;}
Class-based component:
;; Component { return <div>itemname</div>; } { return <VirtualizedItemGrid idealItemWidth=300 items=thispropsitems renderItem=thisrenderItem />; }
Classes with efficient callbacks:
;; Component { event; thisprops; } { return <button onClick=thishandleClick>thispropsname</button>; } Component { console; } { return <MyCard id=itemid name=itemname onClick=thishandleCardClick />; } { return <VirtualizedItemGrid idealItemWidth=300 items=thispropsitems renderItem=thisrenderItem />; }
Props
className
If className
is provided, it will be attached to the outermost Grid div
.
{ return <VirtualizedItemGrid className="my-grid-class" idealItemWidth=300 items=items renderItem=MyCard />;}
idealItemWidth
idealItemWidth
is required and must be either a number or a function which returns a number.
It represents what an ideal width would for each item would be rather than a fixed value.
When using as a function:
{ if containerWidth > 768 return containerWidth / 3; return containerWidth / 2;} { return <VirtualizedItemGrid idealItemWidth=getIdealItemWidth items=items renderItem=MyCard />;}
dynamicRowHeight
If dynamicRowHeight
is true
, which by default it is not, each row will calculate its own height independently. This can lead to performance implications and jagged scrolling for large lists, but if each item has distinct heights, it may be neessary.
items
items
must be an array and should not contain undefined
. Any other value is acceptable, including duplicates, and will be passed along with renderItem
.
renderItem
renderItem
can be a function which returns a React element or a component which renders a React element.
When called as a function, it will receive a single object which contains information about the item. When called as a component, it will receive that information as props.
isVisible
: Whether the item is visible on-screen.isScrolling
: Whether the list is actively being scrolled by the user.columnIndex
: Which 0-based index of the column where the item is located.columnCount
: The total amount of columns of the list. At least 1.columnWidth
: The actual width of each column of the list in pixels.rowIndex
: Which 0-based index of the row where the item is located.rowCount
: The total amount of rows of the list. At least 1.item
: A value of theitems
array.index
: The index of the value within theitems
array.
{ return <div> Visible: isVisible ? 'yes': 'no' Scrolling: isScrolling ? 'yes': 'no' Column Index: StringcolumnIndex Column Count: columnCount Row Index: StringrowIndex Row Count: rowCount Item: JSON Index: Stringindex </div>;} { return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard />;}
overscanRowCount
overscanRowCount
represents the number of rows above and below what is visible on the screen that should be rendered.
If a user were to scroll quickly up or down, they might notice some items being actively rendered. Raising overscanRowCount
prevents this from happening, but uses more resources.
Defaults to 2
.
{ return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard overscanRowCount=4 />;}
header
If header
is provided, a virtual row is placed at the top of the grid which does not affect the items aside from moving them down to make room for the header.
It can be either a React element, a function which returns a React element, or a React Component.
{ return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard header=<h1>My cool list</h1> />;}
{ return <h1>My cool list</h1>;} { return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard header=MyHeader />;}
footer
If footer
is provided, a virtual row is placed at the bottom of the grid which does not affect the items.
It can be either a React element, a function which returns a React element, or a React Component.
{ return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard footer=<h2>Hope you enjoyed</h2> />;}
{ return <h2>Hope you enjoyed</h2>;} { return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard footer=MyFooter />;}
renderCellWrapper
It is not recommended to override renderCellWrapper
, but is possible.
renderCellWrapper
defines the layout placement of each item, header, and footer.
It receives the following properties:
style
: A CSSStyleDeclaration which is intended to be attached to an HTML elementchildren
: The rendered item, header, or footerisHeader
:true
if wrapping a header,false
otherwiseisFooter
:true
if wrapping a footer,false
otherwiseisItem
:true
if wrapping a item,false
otherwise
Only one of isHeader
, isFooter
, or isItem
is true at any given time.
{ return <div style=style>children</div>;} { return <VirtualizedItemGrid idealItemWidth=300 items=items renderItem=MyCard renderCellWrapper=MyCellWrapper />;}