NewYour coding agent can read the release notes before it upgrades.Set up the MCP server β
npm, #3704 most downloaded on npm
<img src="https://react-window.vercel.app/og.png" alt="react-window logo" width="400" height="210" />
Latest stable
2.5.4
Last release today
21 Nov 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
88 releases Β· first in 2014
Drag across the ruler to compare, or tap a release to open it.
Fix lists and grids with a scrollElement not updating their position when content directly before them is removed, or when they are moved ahead of pre
scrollElement not updating their position when content directly before them is removed, or when they are moved ahead of preceding content (e.g. a keyed reorder). - #935List identifies rows by ariaAttributes (specifically aria-posinset ) so that additional children (e.g. sticky rows or overlays) aren't measured as row
List identifies rows by ariaAttributes (specifically aria-posinset) so that additional children (e.g. sticky rows or overlays) aren't measured as rows, and rows that render nothing don't shift the indices of the rows after them. Rows that don't spread ariaAttributes, or that override aria-posinset or aria-setsize, are still matched by their position. If only some rows spread ariaAttributes (e.g. loaded rows but not loading placeholders), the rows that don't are not measured; spread ariaAttributes onto every row (or none). - #930, #931Your coding agent can read these notes before it upgrades. Set up the MCP server β
Add displayName to List and Grid (e.g. for React DevTools and error messages in minified builds). The names are set in a way that does not prevent bun
displayName to List and Grid (e.g. for React DevTools and error messages in minified builds). The names are set in a way that does not prevent bundlers from tree shaking unused components.scrollToRow (and useVirtualizer 's scrollToIndex ) supports behavior: "smooth" for dynamic row heights. The scroll is animated by the list so that its
scrollToRow (and useVirtualizer's scrollToIndex) supports behavior: "smooth" for dynamic row heights. The scroll is animated by the list so that its destination can be corrected as rows are measured along the way. Corrections for a scroll requested while the page is hidden no longer time out before the page is visible again.Add scrollElement prop to List and Grid for lists and grids that scroll along with other content. Pass "window" to scroll with the page, or an ancesto
scrollElement prop to List and Grid for lists and grids that scroll along with other content. Pass "window" to scroll with the page, or an ancestor element that scrolls. The list or grid renders at its full height and only renders the rows visible within the scroll element's viewport; its position within the scroll element is measured whenever it renders, scrolls, or resizes, and whenever content before it is resized, inserted, or removed (e.g. an image loading above it). Imperative scroll methods scroll the scroll element. Grid columns scroll with the scroll element too if the grid is as wide as its content (e.g. style={{ width: "max-content" }}); otherwise they scroll within the grid. Add a scrolling with the page page to the docs site.useVirtualizer hook for rendering custom (headless) virtualized content, e.g. a semantic <table>. It returns the items to render (with their offsets and sizes), the total size, the visible range, and a scrollToIndex method; options mirror the props of List (including scrollElement and dynamic sizes from useDynamicRowHeight). Add a useVirtualizer page to the docs site.useIsScrolling hook for tracking whether a list, grid, or scroll element is scrolling (e.g. to render simplified rows while scrolling). It uses the "scrollend" event where supported. Add a useIsScrolling page to the docs site (replacing the common question about scrolling indicators).scrollToRow, scrollToColumn, scrollToCell, and useVirtualizer's scrollToIndex) respects the CSS scroll-padding of the element being scrolled, like the browser's scrollIntoView. For example, scroll-padding-top can keep rows from being aligned underneath a sticky header.Fix performance issues for fixed-size rows or columns with a size of 0 (e.g. a percentage size before the container has been measured). Rendering no l
"abc%" or negative values) are treated as 0. - #923Add defaultScrollOffset prop to List and defaultScrollLeft / defaultScrollTop props to Grid for setting the initial scroll position. Server-rendered H
Server rendering improvements:
defaultScrollOffset prop to List and defaultScrollLeft/defaultScrollTop props to Grid for setting the initial scroll position. Server-rendered HTML can't be pre-scrolled, so server rendering starts at the first row and the default scroll offset is applied when the component hydrates (unless the browser has already restored a scroll position). For lists and grids that are initially empty (e.g. while data is loading), the offset is applied once they have rows.initialRowHeights option to useDynamicRowHeight for providing row heights that are known or can be estimated ahead of time (e.g. during server rendering).List and Grid logging useLayoutEffect warnings when server rendered with React 18.getScrollbarSize throwing when called during server rendering; it now returns 0.Fix useDynamicRowHeight not measuring rows that set an aria-hidden attribute. - #917
useDynamicRowHeight not measuring rows that set an aria-hidden attribute. - #917List, Grid, and useDynamicRowHeight now use the ResizeObserver, requestAnimationFrame, and document that belong to the window containing the list, rather than the globals of the window that loaded the library. - #918
getScrollbarSize accepts an optional ownerDocument parameter and caches the measured size separately for each document.Fix small perf regression in version 2.3.2 that caused unnecessary size calculations when scrolling beyond cached bounds dynamic sized rows/columns
Improve scrollToRow accuracy for dynamic height rows
scrollToRow accuracy for dynamic height rowsscrollToRow accuracy for rows with dynamic heights. - #914rowKey.rowProps/cellProps being dropped when props are added or removed."33.3%") for row heights and column widths."center" alignment for items near the start or end of a list.Grid updates direction when dir prop changes after mount
dir prop changes after mountGrid not updating its layout direction when the dir prop changes after mount. - #913Add optional rowKey prop to List and add optional rowKey/columnKey prop to Grid.
rowKey prop to List and add optional rowKey/columnKey prop to Grid.rowKey prop to List and optional rowKey/columnKey props to Grid. - #911Fixed a problem with project logo not displaying correctly in the README for the Firefox browser.
useDynamicRowHeight should not instantiate ResizeObserver when server-rendering
useDynamicRowHeight should not instantiate ResizeObserver when server-renderinguseDynamicRowHeight creating a ResizeObserver during server rendering. - #902Use defaultHeight/defaultWidth prop to server render initial set of rows/cells
defaultHeight/defaultWidth prop to server render initial set of rows/cellsrowComponent/cellComponent to work around a ReactNode vs ReactElement mismatch caused by #875Nothing published for this version
Nothing published for this version
Update README docs
Update TS Doc comments for List and Grid imperative methods to specify when a method throws.
List and Grid imperative methods to specify when a method throws.RangeError (instead of a regular Error) if an invalid index is passed to one of the imperative scroll-to methods.The return type of List and Grid components is explicitly annotated as ReactElement. The return type of rowComponent and cellComponent changed from Re
The return type of List and Grid components is explicitly annotated as ReactElement. The return type of rowComponent and cellComponent changed from ReactNode to ReactElement. This was done to fix TypeScript warnings for React versions 18.0 - 18.2. (See issue #875)
Nothing published for this version
Nothing published for this version
Fix possible scroll-jump scenario with useDynamicRowHeight
useDynamicRowHeightNothing published for this version
Support for dynamic row heights via new useDynamicRowHeight hook.
useDynamicRowHeight hook.const rowHeight = useDynamicRowHeight({
defaultRowHeight: 50
});
return <List rowHeight={rowHeight} {...rest} />;
Documentation at: https://react-window-9gegorjnr-brian-vaughns-projects.vercel.app/
useDynamicRowHeight hook. - #857const rowHeight = useDynamicRowHeight({
defaultRowHeight: 50
});
return <List rowHeight={rowHeight} {...rest} />;
Nothing published for this version
Prevent ResizeObserver API from being called at all if an explicit List height (or Grid width and height) is provided.
Prevent ResizeObserver API from being called at all if an explicit List height (or Grid width and height) is provided.
Thanks to @tnajdek for the PR!
Documentation at: https://react-window-8cygyvomv-brian-vaughns-projects.vercel.app/
ResizeObserver API when an explicit List height (or Grid width and height) is provided. - #855Grids with only one row no longer incorrectly set cell height to 100%.
Grids with only one row no longer incorrectly set cell height to 100%.
Documentation at: https://react-window-8cygyvomv-brian-vaughns-projects.vercel.app/
Grid incorrectly setting cell height to 100% when there is only one row.Add better default ARIA attributes for outer HTMLDivElement
Improved ARIA support:
HTMLDivElementariaAttributes prop to row and cell renderers to simplify better ARIA attributes for user-rendered cellsHTMLDivElement from List and Grid
children prop to List and Grid for e.g. overlays/tooltipstagName prop; defaults to "div" but can be changed to e.g. "ul"// Example of how to use new `ariaAttributes` prop
function RowComponent({
ariaAttributes,
index,
style,
...rest
}: RowComponentProps<object>) {
return (
<div style={style} {...ariaAttributes}>
...
</div>
);
}
Added optional children prop to better support edge cases like sticky rows.
Minor changes to onRowsRendered and onCellsRendered callbacks to make it easier to differentiate between visible items and items rendered due to overscan settings. These methods will now receive two paramsβ the first for visible rows and the second for all rows (including overscan), e.g.:
function onRowsRendered(
visibleRows: {
startIndex: number;
stopIndex: number;
},
allRows: {
startIndex: number;
stopIndex: number;
}
): void {
// ...
}
function onCellsRendered(
visibleCells: {
columnStartIndex: number;
columnStopIndex: number;
rowStartIndex: number;
rowStopIndex: number;
},
allCells: {
columnStartIndex: number;
columnStopIndex: number;
rowStartIndex: number;
rowStopIndex: number;
}
): void {
// ...
}
Documentation at: https://react-window-8cygyvomv-brian-vaughns-projects.vercel.app/
HTMLDivElement.ariaAttributes prop to row and cell components, to make it easier to apply the right ARIA attributes to user-rendered rows and cells (see example below).HTMLDivElement from List and Grid, which allows more flexible CSS styling.tagName prop; defaults to "div" but can be changed to e.g. "ul".children prop to List and Grid for content such as overlays, tooltips, or sticky rows.onRowsRendered and onCellsRendered callbacks, to make it easier to tell visible items apart from items rendered because of overscan. The first parameter describes the visible items and the second describes all rendered items (including overscan; see example below).// Example of how to use the new `ariaAttributes` prop
function RowComponent({
ariaAttributes,
index,
style,
...rest
}: RowComponentProps<object>) {
return (
<div style={style} {...ariaAttributes}>
...
</div>
);
}
function onRowsRendered(
visibleRows: {
startIndex: number;
stopIndex: number;
},
allRows: {
startIndex: number;
stopIndex: number;
}
): void {
// ...
}
function onCellsRendered(
visibleCells: {
columnStartIndex: number;
columnStopIndex: number;
rowStartIndex: number;
rowStopIndex: number;
},
allCells: {
columnStartIndex: number;
columnStopIndex: number;
rowStartIndex: number;
rowStopIndex: number;
}
): void {
// ...
}
Nothing published for this version
Fixed edge-case bug with Grid imperative API scrollToCell method and "smooth" scrolling behavior.
Fixed edge-case bug with Grid imperative API scrollToCell method and "smooth" scrolling behavior.
Documentation at: https://react-window-btpcws98u-brian-vaughns-projects.vercel.app/
Grid imperative scrollToCell method when using "smooth" scrolling.Nothing published for this version
Nothing published for this version
Remove ARIA role attribute from List and Grid. This resulted in potentially invalid configurations (e.g. a ARIA _list_ should contain at least one _li
role attribute from List and Grid. This resulted in potentially invalid configurations (e.g. a ARIA list should contain at least one listitem but that was not enforced by this library). Users of this library should specify the role attribute that makes the most sense to them based on mdn guidelines. For example:<List
role="list"
rowComponent={RowComponent}
rowCount={names.length}
rowHeight={25}
rowProps={{ names }}
/>;
function RowComponent({ index, style, ...rest }: RowComponentProps<object>) {
return (
<div role="listitem" style={style}>
...
</div>
);
}
Documentation at: https://react-window-btpcws98u-brian-vaughns-projects.vercel.app/
role attribute from List and Grid. It could produce invalid configurations (e.g. an ARIA list should contain at least one listitem, but this library did not enforce that). Specify the role that makes the most sense for your content, based on MDN guidelines. For example:<List
role="list"
rowComponent={RowComponent}
rowCount={names.length}
rowHeight={25}
rowProps={{ names }}
/>;
function RowComponent({ index, style, ...rest }: RowComponentProps<object>) {
return (
<div role="listitem" style={style}>
...
</div>
);
}
Version 2 is a major rewrite that offers the following benefits:
List and Grid (no more need for AutoSizer)@types/react-window)Version 2 is a major rewrite that offers the following benefits:
Version 2 is a major rewrite that offers the following benefits:
List and Grid (no more need for AutoSizer)@types/react-window)See the documentation for more details, but here is an example of what the v1 to v2 upgrade might look like:
import { FixedSizeList, type ListChildComponentProps } from "react-window";
function Example({ names }: { names: string[] }) {
const itemData = useMemo<ItemData>(() => ({ names }), [names]);
return (
<FixedSizeList
children={Row}
height={150}
itemCount={1000}
itemData={itemData}
itemSize={25}
width={300}
/>
);
}
function Row({
data,
index,
style
}: ListChildComponentProps<{
names: string[];
}>) {
const { names } = data;
const name = names[index];
return <div style={style}>{name}</div>;
}
import { List, type RowComponentProps } from "react-window";
function Example({ names }: { names: string[] }) {
return (
<List
rowComponent={RowComponent}
rowCount={names.length}
rowHeight={25}
rowProps={{ names }}
/>
);
}
function RowComponent({
index,
names,
style
}: RowComponentProps<{
names: string[];
}>) {
const name = names[index];
return <div style={style}>{name}</div>;
}
The following requirements are new in version 2 and may be reasons to consider not upgrading:
ResizeObserver primitive (or polyfill) is required unless explicit pixel dimensions are provided via style prop; (see documentation for more)Documentation at: https://react-window-btpcws98u-brian-vaughns-projects.vercel.app/
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Documentation: https://react-window-v1.vercel.app/
Documentation: https://react-window-v1.vercel.app/
π Fixed scrollDirection when direction is RTL. - #690
scrollDirection when direction is RTL. - #690- README changes.
π scrollToItem accounts for scrollbar size in the uncommon case where a List component has scrolling in the non-dominant direction (e.g. a "vertical"
scrollToItem accounts for scrollbar size in the uncommon case where a List component has scrolling in the non-dominant direction (e.g. a "vertical" layout list also scrolls horizontally).β¨ Updated peer dependencies to include React v18.
β¨ Updated peer dependencies to include React v17.
β¨ Added UMD (dev and prod) build - (emmanueltouzery - #281)
π Fixed size list and grid components now accurately report visibleStopIndex in onItemsRendered. (Previously this value was incorrectly reported as on
visibleStopIndex in onItemsRendered. (Previously this value was incorrectly reported as one index higher.) - (justingrant - #274)scrollToItem "center" mode when the item being scrolled to is near the viewport edge. - (justingrant - #274)π Edge case bug-fix for scrollToItem when scrollbars are present (MarkFalconbridge - #267)
scrollToItem when scrollbars are present (MarkFalconbridge - #267)β¨ Deprecated grid props overscanColumnsCount and overscanRowsCount props in favor of more consistently named overscanColumnCount and overscanRowCount.β¦
overscanColumnsCount and overscanRowsCount props in favor of more consistently named overscanColumnCount and overscanRowCount. (nihgwu - #229)π Replaced an incorrect empty-string value for pointer-events with undefined (oliviertassinari - #210)
pointer-events with undefined (oliviertassinari - #210)π Added new "smart" align option for grid and list scroll-to-item methods (gaearon - #209)
π Add guards to avoid invalid scroll offsets when scrollTo() is called with a negative offset or when scrollToItem is called with invalid indices (neg
scrollTo() is called with a negative offset or when scrollToItem is called with invalid indices (negative or too large).π Fix SSR regression introduced in 1.7.0 - (Betree - #185)
π Grid scrollToItem supports optional rowIndex and columnIndex params (jgoz - #174)
π Bugfix for RTL when scrolling back towards the beginning (right) of the list.
π Bugfix to account for differences between Chrome and non-Chrome browsers with regard to RTL and "scroll" events.
One column per quarter.