react-window README

The project's README from github.com/bvaughn/react-window. As one markdown file: README.md.

react-window logo

react-window is a component library that helps render large lists of data quickly and without the performance problems that often go along with rendering a lot of data. It's used in a lot of places, from React DevTools to the Replay browser.

Support

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

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

Installation

Begin by installing the library from NPM:

npm install react-window

TypeScript types

TypeScript definitions are included within the published dist folder

FAQs

Frequently asked questions can be found here.

Documentation

Documentation for this project is available at react-window.vercel.app; version 1.x documentation can be found at react-window-v1.vercel.app.

List

Renders data with many rows.

Required props

Name Description
rowComponent

React component responsible for rendering a row.

This component will receive an index and style prop by default. Additionally it will receive prop values passed to rowProps.

ℹ️ The prop types for this component are exported as RowComponentProps
rowCount

Number of items to be rendered in the list.
rowHeight

Row height; the following formats are supported:

  • number of pixels (number)
  • percentage of the grid's current height (string)
  • function that returns the row height (in pixels) given an index and cellProps
  • dynamic row height cache returned by the useDynamicRowHeight hook

⚠️ Dynamic row heights are not as efficient as predetermined sizes. It's recommended to provide your own height values if they can be determined ahead of time.
rowProps

Additional props to be passed to the row-rendering component. List will automatically re-render rows when values in this object change.

⚠️ This object must not contain ariaAttributes, index, or style props.

Optional props

Name Description
className

CSS class name.
style

Optional CSS properties. The list of rows will fill the height defined by this style.
children

Additional content to be rendered within the list (above cells). This property can be used to render things like overlays or tooltips.
defaultHeight

Default height of list for initial render. This value is important for server rendering.
listRef

Ref used to interact with this component's imperative API.

This API has imperative methods for scrolling and a getter for the outermost DOM element.

ℹ️ The useListRef and useListCallbackRef hooks are exported for convenience use in TypeScript projects.
onResize

Callback notified when the List's outermost HTMLElement resizes. This may be used to (re)scroll a row into view.
onRowsRendered

Callback notified when the range of visible rows changes.
overscanCount

How many additional rows to render outside of the visible area. This can reduce visual flickering near the edges of a list when scrolling.
rowKey

Lists use the row index as a key by default. This prop can provide a custom key value.

ℹ️ Custom keys can ensure better UX for sortable or filterable lists, particularly if your row components are stateful. Refer to the React documentation for more info.

⚠️ This prop cannot be auto-memoized because it is called during render. It is important to always useCallback for this prop; do not use an inline function.
tagName

Can be used to override the root HTML element rendered by the List component. The default value is "div", meaning that List renders an HTMLDivElement as its root.

⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.

Grid

Renders data with many rows and columns.

ℹ️ Unlike List rows, Grid cell sizes must be known ahead of time. Either static sizes or something that can be derived (from the data in CellProps) without rendering.

Required props

Name Description
cellComponent

React component responsible for rendering a cell.

This component will receive an index and style prop by default. Additionally it will receive prop values passed to cellProps.

ℹ️ The prop types for this component are exported as CellComponentProps
cellProps

Additional props to be passed to the cell-rendering component. Grid will automatically re-render cells when values in this object change.

⚠️ This object must not contain ariaAttributes, columnIndex, rowIndex, or style props.
columnCount

Number of columns to be rendered in the grid.
columnWidth

Column width; the following formats are supported:

  • number of pixels (number)
  • percentage of the grid's current width (string)
  • function that returns the column width (in pixels) given an index and cellProps
rowCount

Number of rows to be rendered in the grid.
rowHeight

Row height; the following formats are supported:

  • number of pixels (number)
  • percentage of the grid's current height (string)
  • function that returns the row height (in pixels) given an index and cellProps

Optional props

Name Description
className

CSS class name.
dir

Indicates the directionality of grid cells.

ℹ️ See HTML dir global attribute for more information.
style

Optional CSS properties. The grid of cells will fill the height and width defined by this style.
children

Additional content to be rendered within the grid (above cells). This property can be used to render things like overlays or tooltips.
columnKey

Grids use the column index as a key by default. This prop can be used along with the rowKey prop to provide a custom key value.

ℹ️ Custom keys can ensure better UX for sortable or filterable grids, particularly if your cell components are stateful. Refer to the React documentation for more info.

⚠️ This prop cannot be auto-memoized because it is called during render. It is important to always useCallback for this prop; do not use an inline function.
defaultHeight

Default height of grid for initial render. This value is important for server rendering.
defaultWidth

Default width of grid for initial render. This value is important for server rendering.
gridRef

Imperative Grid API.

ℹ️ The useGridRef and useGridCallbackRef hooks are exported for convenience use in TypeScript projects.
onCellsRendered

Callback notified when the range of rendered cells changes.
onResize

Callback notified when the Grid's outermost HTMLElement resizes. This may be used to (re)scroll a cell into view.
overscanCount

How many additional rows/columns to render outside of the visible area. This can reduce visual flickering near the edges of a grid when scrolling.
rowKey

Grids use the row index as a key by default. This prop can be used along with the columnKey prop to provide a custom key value.

ℹ️ Custom keys can ensure better UX for sortable or filterable grids, particularly if your cell components are stateful. Refer to the React documentation for more info.

⚠️ This prop cannot be auto-memoized because it is called during render. It is important to always useCallback for this prop; do not use an inline function.
tagName

Can be used to override the root HTML element rendered by the List component. The default value is "div", meaning that List renders an HTMLDivElement as its root.

⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.

react-window (bvaughn/react-window)

Searching Database…

17.2K ·GitHub
React-window
What is this?react-window is a React component library for efficiently rendering large lists and tabular data, avoiding the performance problems that come with rendering huge amounts of DOM elements at once.
Is it a UI framework or just a library of components?It's a lightweight library of two main components, List and Grid, that you drop into your own React app rather than a full framework.
How do I add it to a project?Install it via npm/pnpm as a dependency and import the List or Grid component, passing it a rowComponent/cellComponent plus row/column counts and sizes.
Do I need anything special to use it, like TypeScript?No special runtime dependencies are required beyond React itself; it's written in TypeScript and ships typed props, but plain JavaScript projects can use it too.
Does it work the same for Grid as for List regarding row sizing?List rows can use dynamic heights via a hook, but Grid cell sizes must be known ahead of time (statically or derivable) since they can't be measured after render.
Who typically ends up using this kind of library?Developers building React apps with very large lists or tables, who need smooth scrolling without rendering thousands of offscreen DOM nodes; it's already used inside React DevTools and the Replay browser.
Can I customize row keys for sortable or filterable lists?Yes, both List and Grid accept custom rowKey/columnKey props instead of relying on the default index-based key, which helps stateful rows keep correct UX when sorting or filtering.
Can I change what DOM element the list renders as?Yes, the tagName prop lets you override the root element (default is a div) if the default ARIA roles don't fit your use case.
Does it support server-side rendering?Yes, both List and Grid accept defaultHeight (and Grid also defaultWidth) props specifically to provide sizing for the initial server-rendered output.
How do I interact with the list/grid imperatively, e.g. to scroll to an item?Use the listRef or gridRef props (with the exported useListRef/useGridRef hooks for TypeScript) to get an imperative API for scrolling and accessing the outer DOM element.
What are similar projects?react-virtualized, react-grid-layout, chakra-ui, ink-kit, react-bootstrap, fluentui, react-icons, base-ui
Which topics is it in?react-components, virtualization, component-library, ui-components, performance, react, npm, frontend, library, typescript, web, mit
Creator
bvaughn
Size
9.2 MB
Stars
17.2K
Updated
CommitOct 18Release2.4.1Oct 18
Age
8y
Commits · 90 Days