React Window

Common errors

• Error: FixedSizeList: Each child passed to FixedSizeList or FixedSizeGrid must be a React component. e.g. <FixedSizeList>{MyRow}</FixedSizeList>

  cause This error occurs when you pass an already rendered JSX element or an inline function that returns JSX directly, instead of passing a reference to a functional React component.
  fix Define your row or cell renderer as a separate functional React component (e.g., `const MyRow = ({ index, style }) => <div style={style}>...</div>;`) and then pass its reference to the virtualization component: `<FixedSizeList>{MyRow}</FixedSizeList>`.

• TypeError: Cannot read properties of undefined (reading 'scrollToItem') when calling ref methods.

  cause This usually indicates that the `ref.current` value for `FixedSizeList` or `FixedSizeGrid` is `null` or `undefined` at the time the imperative method (like `scrollToItem`, `scrollTo`) is invoked. This often happens if the ref is not properly attached or accessed before the component has mounted.
  fix Ensure the ref is correctly initialized using `useRef` and that `ref.current` is accessed only after the component is mounted. Calling imperative methods should ideally be done within a `useEffect` hook, a user event handler, or after checking `ref.current` for nullability.

• Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause While a generic React error, when seen with `react-window`, it frequently points to missing or invalid required props for the virtualization component. Specifically, `height`, `width`, `itemCount`, and `itemSize` (for fixed-size components) are critical and must be valid numbers.
  fix Double-check that all mandatory props (`height`, `width`, `itemCount`, `itemSize` for fixed lists/grids, or corresponding size-getter functions for variable lists/grids) are provided and are of the correct type (usually numbers for fixed sizes).

Warnings

• breaking The TypeScript return type for `List` and `Grid` components, as well as the `rowComponent` and `cellComponent` props, was changed from `ReactNode` to `ReactElement`. This adjustment, primarily for React 18 compatibility, ensures stricter type checking and may require minor updates to explicit type annotations in consuming applications if they relied on the broader `ReactNode` type.
  Fix: Ensure custom row/cell components return a valid `ReactElement` (i.e., not `null`, `undefined`, `boolean`, or primitives directly) and update any explicit type annotations from `ReactNode` to `ReactElement` as needed.
• breaking When an invalid index is passed to imperative scroll-to methods (e.g., `scrollToItem`), the library now throws a `RangeError` instead of a generic `Error`. While the error's behavior is similar, the specific error class has changed.
  Fix: If your application relies on catching specific error types from these methods, update `try-catch` blocks to handle `RangeError` explicitly, potentially alongside `Error` for backward compatibility with older versions or other errors.
• gotcha The `useDynamicRowHeight` hook now explicitly avoids instantiating `ResizeObserver` during server-side rendering (SSR) to prevent potential issues like client-side hydration mismatches and unnecessary resource allocation on the server. Dynamic row heights are inherently a client-side concern.
  Fix: When using `useDynamicRowHeight` or other client-side-only features, ensure they are executed exclusively in a browser environment, typically by conditionally rendering components or hooks using `typeof window !== 'undefined'` checks if performing custom SSR logic.

Install

• npm install react-window npm
• yarn add react-window yarn
• pnpm add react-window pnpm

Imports

• FixedSizeList
  wrong:

  const FixedSizeList = require('react-window').FixedSizeList; // Incorrect CommonJS pattern for modern React/TypeScript projects

  correct:

  import { FixedSizeList } from 'react-window'

  The primary component for rendering lists where all items have the same, fixed height.
• VariableSizeList
  wrong:

  import VariableSizeList from 'react-window'; // 'react-window' does not provide a default export for components

  correct:

  import { VariableSizeList } from 'react-window'

  Use this component for lists where items can have varying, dynamically calculated heights.
• FixedSizeGrid
  wrong:

  import { Grid } from 'react-window'; // The fixed-size grid is specifically 'FixedSizeGrid'

  correct:

  import { FixedSizeGrid } from 'react-window'

  Component for rendering 2D grids where all rows and columns have fixed sizes.

Quickstart

Demonstrates a basic setup of `FixedSizeList` to efficiently render 1000 rows, each with a fixed height, within a scrollable container.

import React from 'react';
import { FixedSizeList } from 'react-window';
import { createRoot } from 'react-dom/client';

const Row = ({ index, style }) => {
  // `style` prop is crucial for positioning items correctly
  return (
    <div style={{ ...style, background: index % 2 ? '#eee' : 'white', padding: '10px' }}>
      Item {index + 1}
    </div>
  );
};

const MyVirtualList = () => (
  <FixedSizeList
    height={300} // Total height of the scrollable container
    width={400}  // Total width of the scrollable container
    itemCount={1000} // Total number of items in the list
    itemSize={50}  // Height of each item
  >
    {Row}
  </FixedSizeList>
);

const container = document.getElementById('root');
if (container) {
  const root = createRoot(container);
  root.render(<MyVirtualList />);
}