A windowed grid of elements. Grid
only renders cells necessary to fill itself based on the current horizontal and vertical scroll position. A simple Grid
example can be seen here.
Property | Type | Required? | Description |
---|---|---|---|
autoContainerWidth | Boolean | Set the width of the inner scrollable container to 'auto'. This is useful for single-column Grids to ensure that the column doesn't extend below a vertical scrollbar. | |
autoHeight | Boolean | Outer height of Grid is set to "auto". This property should only be used in conjunction with the WindowScroller HOC. |
|
autoWidth | Boolean | Outer width of Grid is set to "auto". This property should only be used in conjunction with the WindowScroller HOC. |
|
cellRangeRenderer | Function | Responsible for rendering a group of cells given their index ranges. Learn more | |
cellRenderer | Function | ✓ | Responsible for rendering a cell given an row and column index. Learn more |
className | String | Optional custom CSS class name to attach to root Grid element. |
|
columnCount | Number | ✓ | Number of columns in grid. |
columnWidth | Number or Function | ✓ | Either a fixed column width (number) or a function that returns the width of a column given its index: ({ index: number }): number . If function is used, specify estimatedColumnSize for more consistent scrolling behavior. |
containerProps | Object | Responsible for adding props to the cell-container, i.e. onWheel . |
|
containerRole | string | ARIA role for the cell-container; defaults to "rowgroup" | |
containerStyle | Object | Optional custom inline style to attach to inner cell-container element. | |
deferredMeasurementCache | CellMeasurer |
If CellMeasurer is used to measure this Grid's children, this should be a pointer to its CellMeasurerCache. A shared CellMeasurerCache reference enables Grid and CellMeasurer to share measurement data. | |
estimatedColumnSize | Number | Used to estimate the total width of a Grid before all of its columns have actually been measured. The estimated total width is adjusted as columns are rendered. |
|
estimatedRowSize | Number | Used to estimate the total height of a Grid before all of its rows have actually been measured. The estimated total height is adjusted as rows are rendered. |
|
height | Number | ✓ | Height of Grid; this property determines the number of visible (vs virtualized) rows. |
id | String | Optional custom id to attach to root Grid element. |
|
isScrolling | Boolean | Override internal is-scrolling state tracking. This property is primarily intended for use with the WindowScroller component. | |
isScrollingOptOut | Boolean | Prevents re-rendering of visible cells on scroll end. | |
noContentRenderer | Function | Optional renderer to be rendered inside the grid when either rowCount or columnCount is empty: (): PropTypes.node |
|
onSectionRendered | Function | Callback invoked with information about the section of the Grid that was just rendered. This callback is only invoked when visible rows have changed: ({ columnOverscanStartIndex: number, columnOverscanStopIndex: number, columnStartIndex: number, columnStopIndex: number, rowOverscanStartIndex: number, rowOverscanStopIndex: number, rowStartIndex: number, rowStopIndex: number }): void |
|
onScroll | Function | Callback invoked whenever the scroll offset changes within the inner scrollable region: ({ clientHeight: number, clientWidth: number, scrollHeight: number, scrollLeft: number, scrollTop: number, scrollWidth: number }): void |
|
onScrollbarPresenceChange | Function | Called whenever a horizontal or vertical scrollbar is added or removed: ({ horizontal: boolean, size: number, vertical: boolean }): void |
|
overscanColumnCount | Number | Number of columns to render before/after the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. See here for an important note about this property. | |
overscanIndicesGetter | Function | Responsible for calculating the number of cells to overscan before and after a specified range Learn more | |
overscanRowCount | Number | Number of rows to render above/below the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. See here for an important note about this property. | |
role | String | Optional override of ARIA role default; defaults to grid . |
|
rowCount | Number | ✓ | Number of rows in grid. |
rowHeight | Number or Function | ✓ | Either a fixed row height (number) or a function that returns the height of a row given its index: ({ index: number }): number . If function is used, specify estimatedRowSize for more consistent scrolling behavior. |
scrollingResetTimeInterval | Number | Wait this amount of time after the last scroll event before resetting Grid pointer-events ; defaults to 150ms. |
|
scrollLeft | Number | Horizontal offset | |
scrollToAlignment | String | Controls the alignment of scrolled-to-cells. The default ("auto") scrolls the least amount possible to ensure that the specified cell is fully visible. Use "start" to always align cells to the top/left of the Grid and "end" to align them bottom/right. Use "center" to align specified cell in the middle of container. |
|
scrollToColumn | Number | Column index to ensure visible (by forcefully scrolling if necessary). Takes precedence over scrollLeft . |
|
scrollToRow | Number | Row index to ensure visible (by forcefully scrolling if necessary). Takes precedence over scrollTop . |
|
scrollTop | Number | Vertical offset | |
style | Object | Optional custom inline style to attach to root Grid element. |
|
tabIndex | Number | Optional override of tab index default; defaults to 0 . |
|
width | Number | ✓ | Width of Grid; this property determines the number of visible (vs virtualized) columns. |
Gets offsets for a given cell and alignment.
Gets estimated total rows' height.
Gets estimated total columns' width.
This method handles a scroll event originating from an external scroll control. It's an advanced method and should probably not be used unless you're implementing a custom scroll-bar solution.
Pre-measure all columns and rows in a Grid
.
Typically cells are only measured as needed and estimated sizes are used for cells that have not yet been measured. This method ensures that the next call to getTotalSize() returns an exact size (as opposed to just an estimated one).
Recomputes row heights and column widths after the specified index (both default to 0).
This function should be called if dynamic column or row sizes have changed but nothing else has.
Since Grid
only receives columnCount
and rowCount
it has no way of detecting when the underlying data changes.
This method will also force a render cycle (via forceUpdate
) to ensure that the updated measurements are reflected in the rendered grid.
Ensure column and row are visible. This method can be used to safely scroll back to a cell that a user has scrolled away from even if it was previously scrolled to.
Scroll to the specified offset(s). Useful for animating position changes.
The Grid component supports the following static class names
Property | Description |
---|---|
ReactVirtualized__Grid | Main (outer) element |
ReactVirtualized__Grid__innerScrollContainer | Inner scrollable area |
This is an advanced property.
It is useful for situations where the Grid
requires additional, overlayed UI (such as a Gantt chart or a calendar application).
Many use cases can be solved more easily using the onScroll
callback or the ScrollSync
HOC.
If you do want to override cellRangeRenderer
the easiest way is to decorate the default implementation like so:
import { defaultCellRangeRenderer, Grid } from 'react-virtualized'
function cellRangeRenderer (props) {
const children = defaultCellRangeRenderer(props)
children.push(
<div>My custom overlay</div>
)
return children
}
function CustomizedGrid (props) {
return (
<Grid
cellRangeRenderer={cellRangeRenderer}
{...props}
/>
)
}
If you require greater customization, you may want to fork the defaultCellRangeRenderer
function.
This function accepts the following named parameters:
function cellRangeRenderer ({
cellCache, // Temporary cell cache used while scrolling
cellRenderer, // Cell renderer prop supplied to Grid
columnSizeAndPositionManager, // @see CellSizeAndPositionManager,
columnStartIndex, // Index of first column (inclusive) to render
columnStopIndex, // Index of last column (inclusive) to render
horizontalOffsetAdjustment, // Horizontal pixel offset (required for scaling)
isScrolling, // The Grid is currently being scrolled
rowSizeAndPositionManager, // @see CellSizeAndPositionManager,
rowStartIndex, // Index of first row (inclusive) to render
rowStopIndex, // Index of last row (inclusive) to render
scrollLeft, // Current horizontal scroll offset of Grid
scrollTop, // Current vertical scroll offset of Grid
styleCache, // Temporary style (size & position) cache used while scrolling
verticalOffsetAdjustment // Vertical pixel offset (required for scaling)
}) {
const renderedCells = []
for (let rowIndex = rowStartIndex; rowIndex <= rowStopIndex; rowIndex++) {
// This contains :offset (top) and :size (height) information for the cell
let rowDatum = rowSizeAndPositionManager.getSizeAndPositionOfCell(rowIndex)
for (let columnIndex = columnStartIndex; columnIndex <= columnStopIndex; columnIndex++) {
// This contains :offset (left) and :size (width) information for the cell
let columnDatum = columnSizeAndPositionManager.getSizeAndPositionOfCell(columnIndex)
// Be sure to adjust cell position in case the total set of cells is too large to be supported by the browser natively.
// In this case, Grid will shift cells as a user scrolls to increase cell density.
let left = columnDatum.offset + horizontalOffsetAdjustment
let top = rowDatum.offset + verticalOffsetAdjustment
// The rest of the information you need to render the cell are contained in the data.
// Be sure to provide unique :key attributes.
let key = `${rowIndex}-${columnIndex}`
let height = rowDatum.size
let width = columnDatum.size
// Now render your cell and additional UI as you see fit.
// Add all rendered children to the :renderedCells Array.
}
}
return renderedCells
}
This is an advanced property.
This function is responsible for calculating the number of cells to overscan before and after a specified range. By default, React Virtualized optimizes the number of cells to overscan based on scroll direction. If you'd like to customize this behavior, you may want to fork the defaultOverscanIndicesGetter
function.
function overscanIndicesGetter ({
direction, // One of "horizontal" or "vertical"
cellCount, // Number of rows or columns in the current axis
scrollDirection, // 1 (forwards) or -1 (backwards)
overscanCellsCount, // Maximum number of cells to over-render in either direction
startIndex, // Begin of range of visible cells
stopIndex // End of range of visible cells
}) {
return {
overscanStartIndex: Math.max(0, startIndex - overscanCellsCount),
overscanStopIndex: Math.min(cellCount - 1, stopIndex + overscanCellsCount)
}
}
Responsible for rendering a single cell, given its row and column index. This function accepts the following named parameters:
function cellRenderer ({
columnIndex, // Horizontal (column) index of cell
isScrolling, // The Grid is currently being scrolled
isVisible, // This cell is visible within the grid (eg it is not an overscanned cell)
key, // Unique key within array of cells
parent, // Reference to the parent Grid (instance)
rowIndex, // Vertical (row) index of cell
style // Style object to be applied to cell (to position it);
// This must be passed through to the rendered cell element.
}) {
// Grid data is a 2d array in this example...
const user = list[rowIndex][columnIndex]
// If cell content is complex, consider rendering a lighter-weight placeholder while scrolling.
const content = isScrolling
? '...'
: <User user={user} />
// Style is required since it specifies how the cell is to be sized and positioned.
// React Virtualized depends on this sizing/positioning for proper scrolling behavior.
// By default, the grid component provides the following style properties:
// position
// left
// top
// height
// width
// You can add additional class names or style properties as you would like.
// Key is also required by React to more efficiently manage the array of cells.
return (
<div
key={key}
style={style}
>
{content}
</div>
)
}
Below is a very basic Grid
example. The grid displays an array of objects with fixed row and column sizes. (Dynamic sizes are also supported but this example is intended to be basic.) See here for a more full-featured example with dynamic cell sizes and more.
import React from 'react';
import ReactDOM from 'react-dom';
import { Grid } from 'react-virtualized';
// Grid data as an array of arrays
const list = [
['Brian Vaughn', 'Software Engineer', 'San Jose', 'CA', 95125 /* ... */ ]
// And so on...
];
function cellRenderer ({ columnIndex, key, rowIndex, style }) {
return (
<div
key={key}
style={style}
>
{list[rowIndex][columnIndex]}
</div>
)
}
// Render your grid
ReactDOM.render(
<Grid
cellRenderer={cellRenderer}
columnCount={list[0].length}
columnWidth={100}
height={300}
rowCount={list.length}
rowHeight={30}
width={300}
/>,
document.getElementById('example')
);