Skip to content

About

React components for efficiently rendering large lists and tabular data

Topics

Resources

Code of conduct

Contributing

Stars

27.1k stars

Watchers

216 watching

Forks

Latest commit

 

History

2,008 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

react-virtualized logo

react-virtualized is a set of React components for efficiently rendering large lists and tabular data.

Tip

If you're considering adding react-virtualized to a project, take a look at react-window as a possible lighter-weight alternative.

Support

If you like this project there are several ways to support it:

The following wonderful companies and individuals have sponsored react-virtualized:

Installation

Begin by installing the library from NPM:

npm install react-virtualized

Most of react-virtualized's styles are functional (e.g. position, size) and are applied directly to DOM elements. The Table component also ships with a few optional presentational styles; to use them, import the CSS file once (e.g. while bootstrapping your application):

import "react-virtualized/styles.css";

The package is marked as side-effect free (other than its CSS), so bundlers will tree-shake any components you don't use.

TypeScript types

TypeScript definitions are included within the published dist folder. Types are exported for each component's props (e.g. ListProps, GridProps, TableProps) along with the parameters passed to renderers (e.g. RowRendererParams, CellRendererParams, TableCellProps).

Pure components

By default all react-virtualized components are wrapped in memo to avoid re-rendering unless props or state has changed. This occasionally confuses users when a collection's data changes (eg ['a','b','c'] => ['d','e','f']) but props do not (eg array.length).

The solution to this is to let react-virtualized know that something external has changed. This can be done a couple of different ways.

Pass-thru props

This shallow comparison will detect changes to any props, even ones a component doesn't use. This means you can also pass through additional properties that affect cell rendering to ensure changes are detected. For example, if you're using List to render a list of items that may be re-sorted after initial render- react-virtualized would not normally detect the sort operation because none of the properties it deals with change. However you can pass through the additional sort property to trigger a re-render. For example:

<List {...listProps} sortBy={sortBy} />

Public methods

Grid components can be forcefully re-rendered by calling forceUpdate on their ref. For Table and List, you'll need to call forceUpdateGrid to ensure that the inner Grid is also updated. For MultiGrid, you'll need to call forceUpdateGrids to ensure that the inner Grids are updated.

Documentation

Documentation and live examples for every component are available at react-virtualized-docs.vercel.app, along with how-to guides for things like sizing components, infinite loading and server rendering.

Note

AutoSizer is no longer part of react-virtualized (as of version 10); it is available as the separate react-virtualized-auto-sizer package.

Components

ArrowKeyStepper

This HOC decorates a virtualized component and responds to arrow-key events by scrolling one row or column at a time. This provides a snap-to behavior rather than the default browser scrolling behavior.

Note that unlike the other HOCs in react-virtualized, ArrowKeyStepper adds a <div> element around its children in order to attach a key-down event handler. The appearance of this wrapper element can be customized using the className property.

Required props

Name Description
children

Function responsible for rendering children. It is passed onSectionRendered and registerChild parameters, which should be attached to the decorated virtualized component (e.g. <Grid onSectionRendered={onSectionRendered} ref={registerChild} />), and the scrollToColumn and scrollToRow indices of the active cell (e.g. to highlight it). The active cell is scrolled into view through the registered component's scrollToCell method.

columnCount

Number of columns in grid; for Table and List this property should always be 1.

rowCount

Number of rows in grid.

Optional props

Name Description
className

CSS class name to attach to the wrapper <div>.

disabled

Disables all scrolling using arrow-keys.

isControlled

This component is "controlled"; it will not update scrollToColumn or scrollToRow itself. This property should be used with onScrollToChange.

mode

Controls behavior of stepper when arrow key direction changes. "cells" means that the index will only increment or decrement by 1; "edges" means that the opposite side of the grid will be incremented.

onScrollToChange

Called when arrow key navigation should update the current scroll-to values.

scrollToColumn

Default/initial scrollToColumn value. When isControlled is true, this is the current scrollToColumn value.

scrollToRow

Default/initial scrollToRow value. When isControlled is true, this is the current scrollToRow value.

CellMeasurer

Wraps a cell and measures its rendered content. Measurements are stored in a per-cell cache. Cached-content is not be re-measured.

The child must be a DOM element (e.g. <div>) or a component that passes its ref along to one; otherwise use a function child and pass registerChild as the ref of the element to be measured.

Required props

Name Description
cache

Cache to be shared between CellMeasurer and its parent Grid. Typically an instance of CellMeasurerCache.

children

Either a React element as a child (eg <div />) or a function (eg. ({ measure, registerChild }) => <div ref={registerChild} />).

CellMeasurer attaches a ref to the child element to find the DOM element to measure (the child's own ref, if any, still receives the element). So the child must be a DOM element (e.g. <div>) or a component that passes its ref along to one: in React 19, a function component can pass its ref prop to a DOM element; in React 18, function components must use forwardRef for this.

The function receives a measure callback (to re-measure the cell, e.g. after an image has loaded) and a registerChild callback (to specify the DOM element to be measured; can be used as a ref). Use registerChild if the child doesn't pass its ref along to a DOM element, or to measure an element nested within the child.

Children that can't be measured (e.g. text, an array or a fragment, without registerChild) are rendered as-is, and a warning is logged in development mode.

parent

Reference to the parent Grid (or List, Table, MultiGrid, Masonry); this value is passed by Grid to the cellRenderer and should be passed along as-is.

Optional props

Name Description
columnIndex

Index of column being measured (within the parent Grid) or 0 (if used within a List or Table).

index

Index of row being measured; alias of rowIndex (as passed to a List row renderer). Only used if rowIndex is not specified.

rowIndex

Index of row being measured (within the parent Grid). Defaults to index (or 0 if neither is specified).

Column

Describes the header and cell contents of a table column.

This component does not render anything itself; Table reads the props of its children to render headers and cells (applying defaultColumnProps to each child's props). Components that render a Column (e.g. const MyColumn = (props) => <Column {...props} />) can be used as Table children too; their props are read the same way (the wrapper component itself is never rendered).

Required props

Name Description
dataKey

Uniquely identifies the row-data attribute corresponding to this cell (eg this might be "name" in an array of user objects).

width

Flex basis (width) for this column; This value can grow or shrink based on flexGrow and flexShrink properties.

Optional props

Name Description
aria-label

Optional aria-label value to set on the column header.

cellDataGetter

Callback responsible for returning a cell's data, given its dataKey: ({ columnData: any, dataKey: string, rowData: any }): any.

The default cellDataGetter expects to operate on either a vanilla Object or a Map-like object with a get method. You should override it if your data is calculated or requires any custom processing. Defaults to defaultTableCellDataGetter.

cellRenderer

Callback responsible for rendering a cell's contents: ({ cellData: any, columnData: any, columnIndex: number, dataKey: string, isScrolling: boolean, parent: TableImperativeAPI, rowData: any, rowIndex: number }): ReactNode.

The default cellRenderer (defaultTableCellRenderer) displays an attribute as a simple string. You should override it if your data is some other type of object or requires custom formatting.

className

Optional CSS class to apply to the rendered cell container.

columnData

Additional data passed to this column's cellDataGetter, cellRenderer, and headerRenderer. Use this object to relay action-creators or relational data.

defaultSortDirection

Default sort order when clicked for the first time.

disableSort

If sort is enabled for the table at large, disable it for this column.

flexGrow

Flex grow style.

flexShrink

Flex shrink style.

headerClassName

Optional CSS class to apply to this column's header.

headerRenderer

Optional callback responsible for rendering a column's header contents: ({ columnData: any, dataKey: string, disableSort: boolean, label: ReactNode, sortBy: string, sortDirection: SortDirection }): ReactNode.

The default headerRenderer (defaultTableHeaderRenderer) displays the column label along with a sort indicator if the column is sort-enabled and active.

headerStyle

Optional inline style to apply to this column's header.

id

Optional id to set on the column header; used for the cells' aria-describedby.

label

Header label for this column.

maxWidth

Maximum width of column; this property will only be used if flexGrow is greater than 0.

minWidth

Minimum width of column.

style

Optional inline style to apply to the rendered cell container.

ColumnSizer

High-order component that auto-calculates column-widths for Grid cells.

Required props

Name Description
children

Function responsible for rendering a virtualized Grid. It is passed { adjustedWidth, columnWidth, getColumnWidth, registerChild }.

The columnWidth value should be passed to the Grid's columnWidth property, and registerChild should be passed to the Grid's ref property. The adjustedWidth value is optional; it reflects the lesser of the overall width or the width of all columns.

columnCount

Number of columns in the Grid or Table child.

width

Width of the Grid or Table child.

Optional props

Name Description
columnMaxWidth

Optional maximum allowed column width.

columnMinWidth

Optional minimum allowed column width.

Grid

Renders tabular data with virtualization along the vertical and horizontal axes. Row heights and column widths must be known ahead of time and specified as properties.

Scrolling is done through the imperative handle (ref): see scrollToCell and scrollToPosition.

Required props

Name Description
cellRenderer

Responsible for rendering a cell given an row and column index. It receives columnIndex, isScrolling, isVisible, key, parent, rowIndex, and style parameters.

The style parameter specifies how the cell is to be sized and positioned and must be passed through to the rendered cell element. The key parameter must also be applied to the rendered element.

columnCount

Number of columns in grid.

columnWidth

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.

rowCount

Number of rows in grid.

rowHeight

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.

width

Width of Grid; this property determines the number of visible (vs virtualized) columns.

Optional props

Name Description
aria-label

ARIA label for the grid element.

aria-readonly

ARIA readonly attribute for the grid element.

autoContainerWidth

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.

cellRangeRenderer

Responsible for rendering a group of cells given their index ranges.

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). The easiest way to override it is to decorate defaultCellRangeRenderer.

Defaults to defaultCellRangeRenderer.

className

Optional custom CSS class name to attach to root Grid element.

containerProps

Additional props (eg onWheel) to spread onto the outer Grid element.

containerRole

ARIA role for the inner cell-container.

containerStyle

Optional custom inline style to attach to inner cell-container element.

deferredMeasurementCache

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.

elementRef

Reference to the outer (scrolling) DOM element.

estimatedColumnSize

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

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.

getScrollbarSize

Returns the size of the browser's scrollbar. Exposed for testing purposes only.

Defaults to dom-helpers' scrollbarSize (which returns undefined during server rendering).

height

Height of Grid; this property determines the number of visible (vs virtualized) rows. Required, unless a scrollElement is specified.

With a scrollElement, the height of the scroll element's viewport is used instead; this prop is then only used until the scroll element has been measured (e.g. during server rendering).

id

Optional custom id to attach to root Grid element.

initialScrollLeft

Horizontal scroll offset to initially render (and scroll to) the Grid at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the cells at this offset are rendered on the server, and they stay in place when the page is hydrated.

initialScrollTop

Vertical scroll offset to initially render (and scroll to) the Grid at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the cells at this offset are rendered on the server, and they stay in place when the page is hydrated. Ignored if a scrollElement is specified (which then determines the vertical offset).

isScrollingOptOut

Prevents re-rendering of visible cells on scroll end. (Opts out of the isScrolling param passed to cellRangeRenderer, to avoid the extra render when scroll stops.) Visible cells are still re-rendered when the Grid's props change or forceUpdate() is called.

noContentRenderer

Optional renderer to be rendered inside the grid when either rowCount or columnCount is empty. Renders nothing by default.

onScroll

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. This callback can be used to sync scrolling between lists, tables, or grids.

onScrollbarPresenceChange

Called whenever a horizontal or vertical scrollbar is added or removed: ({ horizontal: boolean, size: number, vertical: boolean }): void. This prop is not intended for end-user use; it is used by MultiGrid to support fixed-row/fixed-column scroll syncing.

onSectionRendered

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.

overscanColumnCount

Number of columns to render before/after the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices.

Note that this property has performance implications: the higher the value, the more work needs to be done in reaction to each scroll event. Aim to use the lowest value possible that still generally avoids any empty space from appearing during normal scrolling.

overscanIndicesGetter

Responsible for calculating the number of cells to overscan before and after a specified range. By default, cells are overscanned in the direction the user is scrolling. This function receives direction, cellCount, scrollDirection, overscanCellsCount, startIndex, and stopIndex parameters and returns an { overscanStartIndex, overscanStopIndex } object.

Defaults to defaultOverscanIndicesGetter.

overscanRowCount

Number of rows to render above/below the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices.

Note that this property has performance implications: the higher the value, the more work needs to be done in reaction to each scroll event. The default value (10) is a good starting point; lower it if possible.

role

Optional override of ARIA role default.

scrollElement

Element that scrolls the Grid (instead of the Grid scrolling itself): "window", or a scrollable DOM element (e.g. a container that the Grid is rendered within, along with other content).

The Grid then renders at its full height (it may still scroll horizontally itself), renders only the rows visible within the scroll element's viewport, and its scroll methods scroll the scroll element. Its position within the scroll element is measured when the scroll element scrolls or is resized, and when the Grid re-renders (e.g. call forceUpdate() if content above the Grid changes size without the Grid re-rendering). Pass null while the scroll element isn't available yet (e.g. before a ref to it has been attached); the Grid then renders the rows at its top.

scrollingResetTimeInterval

Wait this amount of time (in milliseconds) after the last scroll event before resetting Grid pointer-events.

style

Optional custom inline style to attach to root Grid element.

tabIndex

Optional override of tab index default.

InfiniteLoader

Higher-order component that manages lazy-loading for "infinite" data. This component decorates a virtual component and just-in-time prefetches rows as a user scrolls. It is intended as a convenience component; fork it if you'd like finer-grained control over data-loading.

Required props

Name Description
children

Function responsible for rendering a virtualized component. It is passed onRowsRendered and registerChild parameters. The onRowsRendered function should be passed through to the child's onRowsRendered property. The registerChild callback should be set as the virtualized component's ref.

isRowLoaded

Function responsible for tracking the loaded state of each row. Rows that are currently loading can be treated as loaded to avoid requesting them multiple times.

loadMoreRows

Callback to be invoked when more rows must be loaded. The returned Promise should be resolved once row data has finished loading. It will be used to determine when to refresh the list with the newly-loaded data. This callback may be called multiple times in reaction to a single scroll event.

Optional props

Name Description
minimumBatchSize

Minimum number of rows to be loaded at a time. This property can be used to batch requests to reduce HTTP requests.

rowCount

Number of rows in list; can be arbitrary high number if actual number is unknown.

threshold

Threshold at which to pre-fetch data. A threshold X means that data will start loading when a user scrolls within X rows.

List

It is inefficient to create and manage a large list of DOM elements within a scrolling container if only a few of those elements are visible. The primary purpose of this component is to improve performance by only rendering the DOM nodes that a user is able to see based on their current scroll position.

This component renders a virtualized list of elements with either fixed or dynamic heights.

Required props

Name Description
rowCount

Number of rows in list.

rowHeight

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.

rowRenderer

Responsible for rendering a row given its index. It receives index, isScrolling, isVisible, key, parent, and style parameters.

The style parameter specifies how the row is to be sized and positioned and must be passed through to the rendered row element. The key parameter must also be applied to the rendered element.

width

Width of the list.

Optional props

Name Description
cellRangeRenderer

Responsible for rendering a group of cells given their index ranges.

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). The easiest way to override it is to decorate defaultCellRangeRenderer.

Defaults to defaultCellRangeRenderer.

containerProps

Additional props (eg onWheel) to spread onto the outer Grid element.

containerStyle

Optional custom inline style to attach to inner cell-container element.

deferredMeasurementCache

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.

elementRef

Reference to the outer (scrolling) DOM element.

getScrollbarSize

Returns the size of the browser's scrollbar. Exposed for testing purposes only.

Defaults to dom-helpers' scrollbarSize (which returns undefined during server rendering).

initialScrollTop

Vertical scroll offset to initially render (and scroll to) the Grid at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the cells at this offset are rendered on the server, and they stay in place when the page is hydrated. Ignored if a scrollElement is specified (which then determines the vertical offset).

isScrollingOptOut

Prevents re-rendering of visible cells on scroll end. (Opts out of the isScrolling param passed to cellRangeRenderer, to avoid the extra render when scroll stops.) Visible cells are still re-rendered when the Grid's props change or forceUpdate() is called.

onScrollbarPresenceChange

Called whenever a horizontal or vertical scrollbar is added or removed: ({ horizontal: boolean, size: number, vertical: boolean }): void. This prop is not intended for end-user use; it is used by MultiGrid to support fixed-row/fixed-column scroll syncing.

scrollingResetTimeInterval

Wait this amount of time (in milliseconds) after the last scroll event before resetting Grid pointer-events.

aria-label

ARIA label for the list element. There is no default label. (With role="grid", it defaults to "grid", as in version 9.)

aria-readonly

ARIA readonly attribute for the list element. Not set by default (it doesn't apply to role="list"); with role="grid", it defaults to true.

containerRole

ARIA role for the inner container of the rows. Defaults to "presentation" (so that the rows belong to the list), or to "row" with role="grid".

role

ARIA role for the list element. With the default "list", rows that don't specify a role get role="listitem" (#1657). Pass "grid" for the version 9 roles (a grid element whose rows are gridcells within a single row).

className

Optional custom CSS class name to attach to root List element.

estimatedRowSize

Used to estimate the total height of a List before all of its rows have actually been measured. The estimated total height is adjusted as rows are rendered.

height

Height constraint for list (determines how many actual rows are rendered). Required, unless a scrollElement is specified.

With a scrollElement, the height of the scroll element's viewport is used instead; this prop is then only used until the scroll element has been measured (e.g. during server rendering).

id

Optional custom id to attach to root List element.

noRowsRenderer

Callback used to render placeholder content when rowCount is 0. By default, nothing is rendered.

onRowsRendered

Callback invoked with information about the slice of rows that were just rendered: ({ overscanStartIndex: number, overscanStopIndex: number, startIndex: number, stopIndex: number }): void.

onScroll

Callback invoked whenever the scroll offset changes within the inner scrollable region: ({ clientHeight: number, scrollHeight: number, scrollTop: number }): void. This callback can be used to sync scrolling between lists, tables, or grids.

overscanIndicesGetter

Responsible for calculating the number of rows to overscan before and after a specified range. By default (accessibilityOverscanIndicesGetter), at least one row is overscanned in each direction (for accessibility). See Grid overscanIndicesGetter for details.

overscanRowCount

Number of rows to render above/below the visible bounds of the list. This can help reduce flickering during scrolling on certain browsers/devices.

Note that this property has performance implications: the higher the value, the more work needs to be done in reaction to each scroll event.

scrollElement

Element that scrolls the List (instead of the List scrolling itself): "window", or a scrollable DOM element (e.g. a container that the List is rendered within, along with other content).

The List then renders at its full height, renders only the rows visible within the scroll element's viewport, and its scroll methods scroll the scroll element. Its position within the scroll element is measured when the scroll element scrolls or is resized, and when the List re-renders (e.g. call forceUpdateGrid() if content above the List changes size without the List re-rendering). Pass null while the scroll element isn't available yet (e.g. before a ref to it has been attached); the List then renders the rows at its top.

style

Optional custom inline style to attach to root List element.

tabIndex

Optional override of tab index default.

Masonry

This component efficiently displays arbitrarily positioned cells using windowing techniques. Cell position is determined by an injected cellPositioner property. Windowing is vertical; this component does not support horizontal scrolling.

Rendering occurs in two phases:

  1. First pass uses estimated cell sizes (provided by the cache) to determine how many cells to measure in a batch. Batch size is chosen using a fast, naive layout algorithm that stacks images in order until the viewport has been filled. After measurement is complete (once the render has been committed) this component evaluates positioned cells in order to determine if another measurement pass is required (eg if actual cell sizes were less than estimated sizes). All measurements are permanently cached (keyed by keyMapper) for performance purposes.
  2. Second pass uses the external cellPositioner to layout cells. At this time the positioner has access to cached size measurements for all cells. The positions it returns are cached by Masonry for fast access later. Phase one is repeated if the user scrolls beyond the current layout's bounds. If the layout is invalidated due to eg a resize, cached positions can be cleared using recomputeCellPositions().

Animation constraints: Simple animations are supported (eg translate/slide into place on initial reveal). More complex animations are not (eg flying from one position to another on resize).

Layout constraints: This component supports multi-column layout. The height of each item may vary. The width of each item must not exceed the width of the column it is "in". The left position of all items within a column must align. (Items may not span multiple columns.)

Required props

Name Description
cellCount

Total number of items.

cellMeasurerCache

Caches item measurements (typically an instance of CellMeasurerCache). Default sizes help Masonry decide how many images to batch-measure.

cellPositioner

Positions a cell given an index: (index: number) => ({ left: number, top: number }). See createMasonryCellPositioner for a built-in positioner.

cellRenderer

Responsible for rendering a cell given an index: ({ index: number, isScrolling: boolean, key: Key, parent: MasonryImperativeAPI, style: CSSProperties }) => ReactNode. The style param must be passed through to the rendered cell element. The cell should typically be wrapped in a CellMeasurer.

width

Width of the component; this value determines the number of visible items.

Optional props

Name Description
aria-label

Optional ARIA label to attach to root Masonry element.

className

Optional custom CSS class name to attach to root Masonry element.

height

Height of the component; this value determines the number of visible items. Required, unless a scrollElement is specified.

With a scrollElement, the height of the scroll element's viewport is used instead; this prop is then only used until the scroll element has been measured (e.g. during server rendering).

id

Optional custom id to attach to root Masonry element.

keyMapper

Maps an index to a unique id to store cached measurement and position info for a cell. This prevents eg cached measurements from being invalidated when a collection is re-ordered. Defaults to the identity function (index => index).

onCellsRendered

Callback invoked with information about the cells that were most recently rendered. This callback is only invoked when visible cells have changed: ({ startIndex: number, stopIndex: number }): void. Does nothing by default.

onScroll

Callback invoked whenever the scroll offset changes within the inner scrollable region: ({ clientHeight: number, scrollHeight: number, scrollTop: number }): void. Does nothing by default.

overscanByPixels

Render this many additional pixels above and below the viewport. This helps reduce flicker when a user scrolls quickly.

role

Optional override of ARIA role default.

rowDirection

Row direction of items; can be "ltr" or "rtl".

scrollElement

Element that scrolls the Masonry (instead of the Masonry scrolling itself): "window", or a scrollable DOM element (e.g. a container that the Masonry is rendered within, along with other content).

The Masonry then renders at its full height, and renders only the cells visible within the scroll element's viewport. Its position within the scroll element is measured when the scroll element scrolls or is resized, and when the Masonry re-renders (e.g. call forceUpdate() if content above the Masonry changes size without the Masonry re-rendering). Pass null while the scroll element isn't available yet (e.g. before a ref to it has been attached); the Masonry then renders the cells at its top.

scrollingResetTimeInterval

Wait this amount of time (in milliseconds) after the last scroll event before resetting pointer-events (and the isScrolling parameter passed to cellRenderer).

style

Optional custom inline style to attach to root Masonry element.

tabIndex

Optional override of tab index default.

MultiGrid

Renders 1, 2, or 4 Grids depending on configuration. A main (body) Grid will always be rendered. Optionally, 1-2 Grids for sticky header rows will also be rendered. If no sticky columns, only 1 sticky header Grid will be rendered. If sticky columns, 2 sticky header Grids will be rendered.

Scrolling is done through the imperative handle (ref): see scrollToCell and scrollToPosition.

Required props

Name Description
cellRenderer

Responsible for rendering a cell given an row and column index. It receives columnIndex, isScrolling, isVisible, key, parent, rowIndex, and style parameters.

The style parameter specifies how the cell is to be sized and positioned and must be passed through to the rendered cell element. The key parameter must also be applied to the rendered element.

columnCount

Number of columns in grid.

columnWidth

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.

rowCount

Number of rows in grid.

rowHeight

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.

width

Width of Grid; this property determines the number of visible (vs virtualized) columns.

height

Height of the MultiGrid (including its fixed rows); determines the number of visible (vs virtualized) rows.

Optional props

Name Description
aria-label

ARIA label for the grid element.

aria-readonly

ARIA readonly attribute for the grid element.

autoContainerWidth

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.

cellRangeRenderer

Responsible for rendering a group of cells given their index ranges.

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). The easiest way to override it is to decorate defaultCellRangeRenderer.

Defaults to defaultCellRangeRenderer.

className

Optional custom CSS class name to attach to root Grid element.

containerProps

Additional props (eg onWheel) to spread onto the outer Grid element.

containerRole

ARIA role for the inner cell-container.

containerStyle

Optional custom inline style to attach to inner cell-container element.

deferredMeasurementCache

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.

elementRef

Reference to the outer (scrolling) DOM element.

estimatedColumnSize

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

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.

getScrollbarSize

Returns the size of the browser's scrollbar. Exposed for testing purposes only.

Defaults to dom-helpers' scrollbarSize (which returns undefined during server rendering).

id

Optional custom id to attach to root Grid element.

initialScrollLeft

Horizontal scroll offset to initially render (and scroll to) the Grid at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the cells at this offset are rendered on the server, and they stay in place when the page is hydrated.

initialScrollTop

Vertical scroll offset to initially render (and scroll to) the Grid at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the cells at this offset are rendered on the server, and they stay in place when the page is hydrated. Ignored if a scrollElement is specified (which then determines the vertical offset).

isScrollingOptOut

Prevents re-rendering of visible cells on scroll end. (Opts out of the isScrolling param passed to cellRangeRenderer, to avoid the extra render when scroll stops.) Visible cells are still re-rendered when the Grid's props change or forceUpdate() is called.

noContentRenderer

Optional renderer to be rendered inside the grid when either rowCount or columnCount is empty. Renders nothing by default.

onScroll

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. This callback can be used to sync scrolling between lists, tables, or grids.

onSectionRendered

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.

overscanColumnCount

Number of columns to render before/after the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices.

Note that this property has performance implications: the higher the value, the more work needs to be done in reaction to each scroll event. Aim to use the lowest value possible that still generally avoids any empty space from appearing during normal scrolling.

overscanIndicesGetter

Responsible for calculating the number of cells to overscan before and after a specified range. By default, cells are overscanned in the direction the user is scrolling. This function receives direction, cellCount, scrollDirection, overscanCellsCount, startIndex, and stopIndex parameters and returns an { overscanStartIndex, overscanStopIndex } object.

Defaults to defaultOverscanIndicesGetter.

overscanRowCount

Number of rows to render above/below the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices.

Note that this property has performance implications: the higher the value, the more work needs to be done in reaction to each scroll event. The default value (10) is a good starting point; lower it if possible.

role

Optional override of ARIA role default.

scrollingResetTimeInterval

Wait this amount of time (in milliseconds) after the last scroll event before resetting Grid pointer-events.

tabIndex

Optional override of tab index default.

classNameBottomLeftGrid

Optional custom className to attach to bottom-left Grid element.

classNameBottomRightGrid

Optional custom className to attach to bottom-right Grid element.

classNameTopLeftGrid

Optional custom className to attach to top-left Grid element.

classNameTopRightGrid

Optional custom className to attach to top-right Grid element.

enableFixedColumnScroll

Fixed columns can be actively scrolled (e.g. with a mouse wheel while the cursor is over them).

enableFixedRowScroll

Fixed rows can be actively scrolled (e.g. with a mouse wheel while the cursor is over them).

fixedColumnCount

Number of fixed columns.

fixedRowCount

Number of fixed rows.

hideBottomLeftGridScrollbar

Optionally hides the bottom-left Grid scrollbar by adding an additional wrapper. Only useful if enableFixedColumnScroll is set to true.

hideTopRightGridScrollbar

Optionally hides the top-right Grid scrollbar by adding an additional wrapper. Only useful if enableFixedRowScroll is set to true.

onScrollbarPresenceChange

Called whenever a horizontal or vertical scrollbar is added or removed from the bottom-right Grid: ({ horizontal: boolean, size: number, vertical: boolean }): void.

style

Optional custom inline style to attach to root MultiGrid element.

styleBottomLeftGrid

Optional custom inline style to attach to bottom-left Grid element.

styleBottomRightGrid

Optional custom inline style to attach to bottom-right Grid element.

styleTopLeftGrid

Optional custom inline style to attach to top-left Grid element.

styleTopRightGrid

Optional custom inline style to attach to top-right Grid element.

ScrollSync

HOC that simplifies the process of synchronizing scrolling between two or more virtualized components.

Required props

Name Description
children

Function responsible for rendering 2 or more virtualized components. It is passed the current scroll and size values (clientHeight, clientWidth, scrollHeight, scrollLeft, scrollTop, scrollWidth), an onScroll callback that should be passed through to the virtualized children that the user can scroll, and a registerChild function that returns a ref callback for each virtualized child that should be kept in sync (e.g. <Grid ref={registerChild("body")} onScroll={onScroll} />). The scroll and size values can also be used for custom rendering (e.g. shading based on the scroll offset).

Optional props

None

Table

Table component with fixed headers and virtualized rows for improved performance with large data sets. This component expects explicit width, height, and padding parameters.

Columns are described by Column children (or components that render a Column). Scrolling is done through the imperative handle (ref): see scrollToRow, scrollToCell, and scrollToPosition.

Required props

Name Description
rowCount

Number of rows in table.

rowGetter

Callback responsible for returning a data row given an index: ({ index: number }): any.

rowHeight

Either a fixed row height (number) or a function that returns the height of a row given its index: ({ index: number }): number.

width

Width of the table.

Optional props

Name Description
cellRangeRenderer

Responsible for rendering a group of cells given their index ranges.

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). The easiest way to override it is to decorate defaultCellRangeRenderer.

Defaults to defaultCellRangeRenderer.

containerProps

Additional props (eg onWheel) to spread onto the outer Grid element.

containerRole

ARIA role for the inner cell-container.

containerStyle

Optional custom inline style to attach to inner cell-container element.

getScrollbarSize

Returns the size of the browser's scrollbar. Exposed for testing purposes only.

Defaults to dom-helpers' scrollbarSize (which returns undefined during server rendering).

isScrollingOptOut

Prevents re-rendering of visible cells on scroll end. (Opts out of the isScrolling param passed to cellRangeRenderer, to avoid the extra render when scroll stops.) Visible cells are still re-rendered when the Grid's props change or forceUpdate() is called.

onScrollbarPresenceChange

Called whenever a horizontal or vertical scrollbar is added or removed: ({ horizontal: boolean, size: number, vertical: boolean }): void. This prop is not intended for end-user use; it is used by MultiGrid to support fixed-row/fixed-column scroll syncing.

scrollingResetTimeInterval

Wait this amount of time (in milliseconds) after the last scroll event before resetting Grid pointer-events.

aria-label

ARIA label set on the outer Table element.

aria-labelledby

ARIA labelledby attribute set on the outer Table element.

children

One or more Columns describing the data displayed in this table. Falsy children are ignored, to allow easier dynamic showing/hiding of columns.

Table reads the props of its children (with defaultColumnProps applied) without rendering them, so components that wrap Column (e.g. const MyColumn = (props: ColumnProps) => <Column {...props} />) can be used as children too. (Subclassing Column is no longer supported.)

className

Optional custom CSS class name to attach to root Table element.

deferredMeasurementCache

If CellMeasurer is used to measure this Table's cells, this should be a pointer to its CellMeasurerCache. It is passed through to the inner Grid.

disableHeader

Do not render the table header (only the rows).

estimatedRowSize

Used to estimate the total height of a Table before all of its rows have actually been measured. The estimated total height is adjusted as rows are rendered.

gridClassName

Optional custom CSS class name to attach to inner Grid element.

gridStyle

Optional inline style to attach to inner Grid element.

headerClassName

Optional CSS class to apply to all column headers.

headerHeight

Fixed height of header row.

headerRowRenderer

Responsible for rendering the table header row given an array of columns: ({ className: string, columns: ReactNode[], style: CSSProperties }): ReactNode.

This is an advanced property. It is useful for situations where you require additional hooks into Table to render additional custom UI elements. You may want to start by forking the defaultTableHeaderRowRenderer function (the default).

headerStyle

Optional custom inline style to attach to table header columns.

height

Fixed/available height for the outer DOM element. Required, unless a scrollElement is specified.

With a scrollElement, the height of the scroll element's viewport is used instead; this prop is then only used until the scroll element has been measured (e.g. during server rendering).

id

Optional custom id to attach to root Table element.

initialScrollTop

Vertical scroll offset to initially render (and scroll to) the Table at. Only the initial value is used: changing this prop later has no effect (use scrollToPosition to scroll). This also works with server rendering: the rows at this offset are rendered on the server, and they stay in place when the page is hydrated. Ignored if a scrollElement is specified (which then determines the vertical offset).

noRowsRenderer

Optional renderer to be used in place of table body rows when rowCount is 0.

onColumnClick

Callback invoked when a user clicks on a table column (cell): ({ columnData: any, dataKey: string, event: Event }): void.

onHeaderClick

Callback invoked when a user clicks on (or activates via the ENTER or SPACE key) a table header: ({ columnData: any, dataKey: string, event: Event }): void.

onRowClick

Callback invoked when a user clicks on a table row: ({ event: Event, index: number, rowData: any }): void.

onRowDoubleClick

Callback invoked when a user double-clicks on a table row: ({ event: Event, index: number, rowData: any }): void.

onRowMouseOut

Callback invoked when the mouse leaves a table row: ({ event: Event, index: number, rowData: any }): void.

onRowMouseOver

Callback invoked when a user moves the mouse over a table row: ({ event: Event, index: number, rowData: any }): void.

onRowRightClick

Callback invoked when a user right-clicks on a table row: ({ event: Event, index: number, rowData: any }): void.

onRowsRendered

Callback invoked with information about the slice of rows that were just rendered: ({ overscanStartIndex: number, overscanStopIndex: number, startIndex: number, stopIndex: number }): void.

onScroll

Callback invoked whenever the scroll offset changes within the inner scrollable region: ({ clientHeight: number, scrollHeight: number, scrollTop: number }): void. This callback can be used to sync scrolling between lists, tables, or grids.

overscanIndicesGetter

Responsible for calculating the number of rows to overscan before and after a specified range (see Grid overscanIndicesGetter). By default (accessibilityOverscanIndicesGetter), Table overscans by at least one row in each direction (for accessibility).

overscanRowCount

Number of rows to render above/below the visible bounds of the list. This can help reduce flickering during scrolling on certain browsers/devices.

rowClassName

Optional CSS class to apply to all table rows (including the header row). This value may be either a static string or a function with the signature ({ index: number }): string. Note that for the header row an index of -1 is provided.

rowRenderer

Responsible for rendering a table row given an array of columns.

This is an advanced property. It is useful for situations where you require additional hooks into Table (eg integration with a library like react-sortable-hoc). The easiest way to override it is to decorate (or fork) the defaultTableRowRenderer function (the default).

rowStyle

Optional custom inline style to attach to table rows (including the header row). This value may be either a style object or a function with the signature ({ index: number }): CSSProperties. Note that for the header row an index of -1 is provided.

sort

Sort function to be called if a sortable header is clicked: ({ defaultSortDirection: SortDirection, event: Event, sortBy: string, sortDirection: SortDirection }): void.

sortBy

Data is currently sorted by this dataKey (if it is sorted at all).

sortDirection

Data is currently sorted in this direction (if it is sorted at all).

scrollElement

Element that scrolls the Table (instead of the Table scrolling itself): "window", or a scrollable DOM element (e.g. a container that the Table is rendered within, along with other content).

The Table then renders all of its rows at their full height (below its header, which scrolls along with them), renders only the rows visible within the scroll element's viewport, and its scroll methods scroll the scroll element. Its position within the scroll element is measured when the scroll element scrolls or is resized, and when the Table re-renders (e.g. call forceUpdateGrid() if content above the Table changes size without the Table re-rendering). Pass null while the scroll element isn't available yet (e.g. before a ref to it has been attached); the Table then renders the rows at its top.

style

Optional custom inline style to attach to root Table element.

tabIndex

Optional override of inner Grid tab index default.

Imperative APIs

ArrowKeyStepperImperativeAPI

Public methods available on an ArrowKeyStepper ref.

Methods

Name Description
setScrollIndexes

Override the local state of the component with new values for scrollToRow and scrollToColumn.

CellMeasurerCacheAPI

Public API of a CellMeasurerCache instance.

Methods

Name Description
clear

Reset cached measurements for a specific cell. This should be called when a cell needs to be re-measured to handle dynamic content (e.g. replacing a loading indicator with loaded content, or reacting to state changes for stateful cells). columnIndex defaults to 0.

clearAll

Reset cached measurements for all cells. This should be called when a Grid, List or Table needs to reflow its content due to a resize in a responsive layout (e.g. a change in window width may impact the height of cells).

columnWidth

Returns the derived width of a column (its widest measured cell) or the default width. Pass this as the columnWidth prop of a Grid (or MultiGrid); it's bound to the cache, so it can be passed as-is.

getHeight

Returns the (measured or default) height of the specified cell. columnIndex defaults to 0.

getWidth

Returns the (measured or default) width of the specified cell. columnIndex defaults to 0.

has

Returns true if the specified cell has already been measured. columnIndex defaults to 0.

hasFixedHeight

Returns true if cells have a fixed height (and a dynamic, measured width); see the fixedHeight option.

hasFixedWidth

Returns true if cells have a fixed width (and a dynamic, measured height); see the fixedWidth option.

rowHeight

Returns the derived height of a row (its tallest measured cell) or the default height. Pass this as the rowHeight prop of a Grid, List or Table; it's bound to the cache, so it can be passed as-is.

set

Stores the measured size of the specified cell. This is called by CellMeasurer and doesn't usually need to be called directly.

GridImperativeAPI

Public (imperative) methods of a Grid (its ref handle).

Methods

Name Description
forceUpdate

Forcefully re-render the Grid (and its visible cells), e.g. because the data rendered by cellRenderer has changed but the Grid's props have not.

getOffsetForCell

Gets offsets for a given cell and alignment (see scrollToCell for the alignment values). The alignment defaults to "auto"; an index of -1 (the default) refers to the last column or row.

getTotalRowsHeight

Gets estimated total rows' height.

getTotalColumnsWidth

Gets estimated total columns' width.

handleScrollEvent

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.

invalidateCellSizeAfterRender

Invalidate the size of a cell and recompute visible cells after the current render has been committed. This is a deferred version of recomputeGridSize() (batching the invalidations of a render); it is intended for advanced use-cases like CellMeasurer.

measureAllCells

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).

recomputeGridSize

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 to ensure that the updated measurements are reflected in the rendered grid.

scrollToCell

Ensure the specified column and/or row is visible (scrolling if necessary). 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. The align parameter (default "auto") controls the alignment of the cell: "auto" scrolls the least amount possible to ensure that the specified cell is fully visible (a cell larger than the Grid is aligned to its start, so that its start is visible); "start" aligns the cell to the top/left of the Grid and "end" to the bottom/right; "center" aligns the cell in the middle of the Grid. This is a one-time scroll: the cell is not kept in view afterwards (e.g. if the Grid's size or its cell sizes change). Cells that haven't been measured yet (e.g. by CellMeasurer) are positioned using their estimated sizes. Nothing is scrolled while the Grid's width or height is 0. The column is ignored for single-column grids (e.g. List, Table). If the Grid has a scrollElement, the scroll element (e.g. the window) is scrolled vertically instead.

scrollToPosition

Scroll to the specified offset(s); an omitted offset is left unchanged. Offsets are clamped to the scrollable range. Calling this method with the current offsets does nothing. If the Grid has a scrollElement, scrollTop scrolls the scroll element (e.g. the window) instead (to the position at which the Grid is scrolled by scrollTop).

InfiniteLoaderImperativeAPI

Imperative API exposed by InfiniteLoader (e.g. via useRef<InfiniteLoaderImperativeAPI>(null)).

Methods

Name Description
resetLoadMoreRowsCache

Reset any cached data about already-loaded rows. This method should be called if any/all loaded data needs to be refetched (e.g. a filtered list where the search criteria changes). If autoReload is true, the last loaded batch will be automatically reloaded.

ListImperativeAPI

Public (imperative) methods of a List (its ref handle). The handle is also passed to rowRenderer as parent (e.g. for CellMeasurer).

Methods

Name Description
forceUpdateGrid

Forcefully re-render the inner Grid component. Re-rendering a List with the same props does not re-render its rows (both List and the inner Grid are memoized). Use this method if you want to manually trigger a re-render. This may be appropriate if the underlying row data has changed but the row sizes themselves have not.

getOffsetForRow

Gets the vertical offset (scrollTop) for a given row and alignment (see scrollToRow for the align values). The alignment defaults to "auto"; an index of -1 (the default) refers to the last row. alignment is a deprecated alias of align (align takes precedence if both are specified).

invalidateCellSizeAfterRender

Invalidate the size of a row (after the current render has been committed); see Grid#invalidateCellSizeAfterRender. This method is intended for CellMeasurer.

measureAllRows

Pre-measure all rows in a List. Typically rows are only measured as needed and estimated heights 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).

recomputeRowHeights

Recompute row heights and offsets after the specified index (defaults to 0). List has no way of knowing when its underlying list data has changed since it only receives a rowHeight property. If the rowHeight is a number it can compare before and after values but if it is a function that comparison is error prone. In the event that a dynamic rowHeight function is in use and the row heights have changed this function should be manually called by the "smart" container parent. This method will also force a render cycle (via forceUpdate) to ensure that the updated measurements are reflected in the rendered list.

recomputeGridSize

Recompute row heights and offsets after the specified row index (defaults to 0); see Grid#recomputeGridSize. (The column index is ignored.) This method is intended for CellMeasurer; also see recomputeRowHeights.

scrollToCell

Ensure the specified row is visible (scrolling if necessary); the column index is ignored. This allows a List to be used with ArrowKeyStepper; also see scrollToRow.

scrollToPosition

Scroll to the specified vertical offset; scrollLeft is ignored (lists don't scroll horizontally). Offsets are clamped to the scrollable range. This allows a List to be used with ScrollSync. Useful for animating position changes. If the List has a scrollElement, the scroll element (e.g. the window) is scrolled instead.

scrollToRow

Ensure the row at the specified index is visible (scrolling if necessary). This method can be used to safely scroll back to a row that a user has scrolled away from even if it was previously scrolled to. The align parameter (default "auto") controls the alignment of the row: "auto" scrolls the least amount possible to ensure that the specified row is fully visible (a row taller than the list is aligned to its start, so that its start is visible); "start" aligns the row to the top of the list and "end" to the bottom; "center" aligns it in the middle. This is a one-time scroll: the row is not kept in view afterwards (e.g. if the list's size or its row heights change). Rows that haven't been measured yet (e.g. by CellMeasurer) are positioned using their estimated heights. If the List has a scrollElement, the scroll element (e.g. the window) is scrolled instead.

MasonryImperativeAPI

Imperative API of a Masonry (accessed using a ref, eg useRef<MasonryImperativeAPI>(null)). This is also the parent value passed to cellRenderer (for CellMeasurer).

Methods

Name Description
clearCellPositions

Clears the internal position cache and re-renders. Cells are positioned again (by the cellPositioner) as they are rendered.

forceUpdate

Forcefully re-renders the Masonry (and its visible cells). Re-rendering a Masonry with the same props does not re-render its cells (it is memoized). Use this method if the underlying cell data has changed but the props have not.

invalidateCellSizeAfterRender

Notifies the Masonry that the specified cell has been measured for the first time (while rendering); the cell is positioned (by the cellPositioner) once the current render has been committed, then the Masonry re-renders. Only rowIndex (the cell's index) is used. This method is intended for CellMeasurer.

recomputeCellPositions

Resets the internal position cache, synchronously re-computes the positions of all measured cells (by calling the cellPositioner for each of them, in index order), then re-renders. Reset the cellPositioner (e.g. with its reset method) before calling this method.

recomputeGridSize

Re-renders the Masonry, e.g. after more cells have been loaded (this method is called by InfiniteLoader) or a cell has been re-measured (it is called by CellMeasurer's measure function). Parameters (the index of the first changed cell, as rowIndex) are accepted for compatibility with Grid and ignored. Cached cell positions are not changed: to re-position cells after their sizes have changed, reset the cellPositioner and call recomputeCellPositions().

MultiGridImperativeAPI

Public (imperative) methods of a MultiGrid instance.

Methods

Name Description
forceUpdateGrids

Pass-thru that calls forceUpdate on all child Grids.

invalidateCellSizeAfterRender

Invalidate the size of a cell (after the current render has been committed); see Grid#invalidateCellSizeAfterRender. The invalidated cells (of all child Grids) are recomputed, and the MultiGrid re-rendered, once the current render has been committed. This method is intended for CellMeasurer.

measureAllCells

Pass-thru that calls measureAllCells on all child Grids.

recomputeGridSize

Pass-thru that calls recomputeGridSize on all child Grids (adjusting the specified indices for fixed rows and columns). Both indices default to 0. This also recomputes the MultiGrid's own layout (the height of the fixed rows and the width of the fixed columns) and re-renders it.

scrollToCell

Ensure the specified column and/or row is visible (scrolling if necessary); see Grid#scrollToCell. Indices include the fixed columns and rows (which are always visible, so they are not scrolled to). The fixed rows and columns are kept in sync with the scrolled section.

scrollToPosition

Scroll to the specified offset(s) of the scrollable (bottom-right) section; see Grid#scrollToPosition. The fixed rows and columns are kept in sync with it. This allows a MultiGrid to be used with ScrollSync.

TableImperativeAPI

Public (imperative) methods of a Table instance.

Methods

Name Description
forceUpdateGrid

Forcefully re-render the inner Grid component. Calling forceUpdate on Table may not re-render the inner Grid since it uses shallowCompare as a performance optimization. Use this method if you want to manually trigger a re-render. This may be appropriate if the underlying row data has changed but the row sizes themselves have not.

getOffsetForRow

Gets offset for a given row and alignment (align; alignment is a deprecated alias). The alignment defaults to "auto"; an index of -1 (the default) refers to the last row.

getScrollbarWidth

Gets the scrollbar width used to pad the table-header.

invalidateCellSizeAfterRender

Invalidate the size of a row (after the current render has been committed); see Grid#invalidateCellSizeAfterRender. This method is intended for CellMeasurer.

measureAllRows

Pre-measure all rows in a Table. Typically rows are only measured as needed and estimated heights 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).

recomputeRowHeights

Recompute row heights and offsets after the specified index (defaults to 0). Table has no way of knowing when its underlying list data has changed since it only receives a rowHeight property. If the rowHeight is a number it can compare before and after values but if it is a function that comparison is error prone. In the event that a dynamic rowHeight function is in use and the row heights have changed this function should be manually called by the "smart" container parent. This method will also force a render cycle (via forceUpdate) to ensure that the updated measurements are reflected in the rendered table.

recomputeGridSize

Recompute row heights and offsets after the specified row index (defaults to 0); see Grid#recomputeGridSize. (The column index is ignored.) This method is intended for CellMeasurer; also see recomputeRowHeights.

scrollToCell

Ensure the specified row is visible (scrolling if necessary); the column index is ignored. This allows a Table to be used with ArrowKeyStepper; also see scrollToRow.

scrollToPosition

Scroll to the specified vertical offset; scrollLeft is ignored (tables don't scroll horizontally). Offsets are clamped to the scrollable range. This allows a Table to be used with ScrollSync. Useful for animating position changes. If the Table has a scrollElement, the scroll element (e.g. the window) is scrolled instead.

scrollToRow

Ensure the row at the specified index is visible (scrolling if necessary). This method can be used to safely scroll back to a row that a user has scrolled away from even if it was previously scrolled to. The align parameter (default "auto") controls the alignment of the row: "auto" scrolls the least amount possible to ensure that the specified row is fully visible (a row taller than the table is aligned to its start, so that its start is visible); "start" aligns the row to the top of the table and "end" to the bottom; "center" aligns it in the middle. This is a one-time scroll: the row is not kept in view afterwards (e.g. if the table's size or its row heights change). Rows that haven't been measured yet (e.g. by CellMeasurer) are positioned using their estimated heights. If the Table has a scrollElement, the scroll element (e.g. the window) is scrolled instead.

About

React components for efficiently rendering large lists and tabular data

Topics

Resources

Code of conduct

Contributing

Stars

27.1k stars

Watchers

216 watching

Forks

Releases

Packages

Used by

Contributors

Languages