React Virtualized Components

Common errors

• Element type is invalid: expected a string (for built-in components) or a class/function (for composite components)

  cause This error typically occurs when React cannot resolve the component imported from `react-virtualized`. This can be due to incorrect import paths, a mismatched React version, or multiple instances of React loaded in the application.
  fix Verify that `react` and `react-dom` peer dependencies are met. Ensure you are using named imports correctly (e.g., `import { List } from 'react-virtualized'`). Check your bundler configuration for potential duplicate React instances.

• TypeError: Cannot read properties of undefined (reading 'length')

  cause Occurs when the data source (e.g., `list` prop for `List` or `rowCount`) passed to a virtualized component is `undefined` or `null` instead of an array or a number, especially during initial render or asynchronous data loading.
  fix Ensure that the data array or `rowCount` is always initialized, even if empty, before rendering the virtualized component. For asynchronous data, conditionally render the component after data is loaded or provide a default empty array/zero count.

• Uncaught TypeError: Cannot read properties of null (reading 'scrollTop')

  cause This error often indicates that you're attempting to access a method or property on a `react-virtualized` component instance (e.g., via a ref) before the component has been mounted to the DOM or if the ref is not properly assigned.
  fix Ensure that any imperative calls on component refs are made only after the component has mounted (e.g., within `useEffect` with an empty dependency array or after a render). Double-check ref assignment and `null` checks before accessing ref properties.

Warnings

• breaking Recent minor versions (9.22.4, 9.22.6) updated peer dependencies to include React 17, 18, and 19. While this aims for compatibility, ensure your project's React version aligns with these requirements to avoid potential build or runtime issues due to mismatched React contexts.
  Fix: Update your `react` and `react-dom` packages to versions compatible with `^16.3.0 || ^17.0.0 || ^18.0.0 || ^19.0.0`. Check `npm list react` and `npm list react-dom` to identify multiple or incompatible React instances.
• gotcha Achieving optimal performance with virtualized lists often requires stable props. Frequent changes to `rowHeight`, `rowCount`, or `rowRenderer` (if not memoized) can negate the performance benefits of virtualization, leading to unnecessary re-renders.
  Fix: Memoize `rowRenderer` using `useCallback`, ensure `rowHeight` and `rowCount` are stable values or derived from stable state/props. For dynamic row heights, use `CellMeasurer` or ensure a well-defined `getRowHeight` function.
• gotcha Incorrectly configuring `width` and `height` props for `List`, `Table`, or `Grid` components can result in blank content or unexpected scroll behavior. These components require explicit dimensions or need to be wrapped in a container that provides them (e.g., `AutoSizer`).
  Fix: Always provide explicit `width` and `height` props to virtualized components, or wrap them in an `<AutoSizer>` component to dynamically fill their parent's dimensions. Ensure the parent container of `AutoSizer` also has defined dimensions.

Install

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

Imports

• List
  wrong:

  const List = require('react-virtualized')

  correct:

  import { List } from 'react-virtualized'

  Use named import for modern ESM environments. CommonJS `require` might work in some setups but is not the recommended approach for this library with contemporary React.
• Table
  wrong:

  import Table from 'react-virtualized/dist/commonjs/Table'

  correct:

  import { Table, Column } from 'react-virtualized'

  Most components are exported as named exports directly from the main package. Avoid deep imports unless explicitly necessary or for older CommonJS setups.
• AutoSizer
  wrong:

  import { AutoSizer } from 'react-virtualized/lib/AutoSizer'

  correct:

  import { AutoSizer } from 'react-virtualized'

  AutoSizer is crucial for dynamically sizing virtualized components to fill available space without manual width/height calculations. Prefer top-level named imports.
• ListRowRenderer
  wrong:

  type ListRowRenderer = ({ index, key, style, parent }: ListRowProps) => React.ReactNode

  correct:

  import { ListRowRenderer } from 'react-virtualized'

  Import the type directly for type safety in TypeScript projects. Do not manually define the interface or type.

Quickstart

This example demonstrates how to create a basic virtualized list using `List` and `AutoSizer` components, efficiently rendering 10,000 items with a fixed row height.

import React, { useRef, useCallback } from 'react';
import { List, AutoSizer, ListRowRenderer } from 'react-virtualized';
import 'react-virtualized/styles.css'; // Essential for basic styling

interface Item {
  id: number;
  name: string;
  description: string;
}

const generateData = (count: number): Item[] => {
  const data: Item[] = [];
  for (let i = 0; i < count; i++) {
    data.push({
      id: i,
      name: `Item ${i}`,
      description: `This is the description for item number ${i}. It can be quite long, demonstrating content within a virtualized row.`
    });
  }
  return data;
};

const items = generateData(10000); // Generate 10,000 dummy items

function MyVirtualizedList() {
  const listRef = useRef<List>(null);

  const rowRenderer: ListRowRenderer = useCallback(({ index, key, style }) => {
    const item = items[index];
    return (
      <div key={key} style={{ ...style, borderBottom: '1px solid #eee', padding: '10px' }}>
        <h3 style={{ margin: 0 }}>{item.name}</h3>
        <p style={{ margin: '5px 0 0' }}>{item.description}</p>
      </div>
    );
  }, [items]); // Dependencies for useCallback to prevent unnecessary re-renders

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <AutoSizer>
        {({ width, height }) => (
          <List
            ref={listRef}
            width={width}
            height={height}
            rowCount={items.length}
            rowHeight={80} // Fixed height for simplicity; dynamic heights require more complex setup
            rowRenderer={rowRenderer}
            overscanRowCount={3} // Render a few extra rows for smoother scrolling
          />
        )}
      </AutoSizer>
    </div>
  );
}

export default MyVirtualizedList;