React Virtuoso

Common errors

• Error: Virtuoso container has no height.

  cause The Virtuoso component or its parent container does not have an explicit CSS height property defined.
  fix Apply a `style={{ height: '...' }}` or `style={{ maxHeight: '...' }}` to the `Virtuoso` component or its parent element. For example, `style={{ height: '100%' }}`.

• Error: zero-sized element, this should not happen

  cause This error typically indicates that an item rendered by Virtuoso has zero height or width, which is not supported, or there's an exotic integration bug.
  fix Ensure that items rendered by `itemContent` are not empty and have a measurable size. Check for any CSS that might inadvertently collapse the item's dimensions. Enable debug logging (`logLevel={LogLevel.DEBUG}`) to inspect item sizes.

• Module parse failed: You may need an appropriate loader to handle this file type.

  cause This error usually occurs in older build environments (e.g., Webpack 4) when importing modern JavaScript modules (like ES Modules in `.mjs` files) without proper configuration.
  fix Update your build tools (Webpack, Babel) to support ES Modules. Ensure your Webpack configuration includes a rule to process `.mjs` files if present, or upgrade to Webpack 5+.

• TypeError: itemContent is not a function

  cause The `itemContent` prop, which is a render prop, was not provided as a function.
  fix Ensure that the `itemContent` prop is always passed a function that accepts `index` (and `groupIndex` for `GroupedVirtuoso`) and returns a React element. For example: `itemContent={(index) => <div>Item {index}</div>}`.

Warnings

• breaking Older versions of `react-virtuoso` (prior to 4.18.5) had an issue with `useSyncExternalStore` detection for React 19+, falling back to a legacy subscription path which could cause 'tearing issues' in concurrent rendering scenarios. This was due to a version check that incorrectly excluded React 19.
  Fix: Upgrade `react-virtuoso` to version `4.18.5` or higher to ensure proper `useSyncExternalStore` detection and avoid tearing issues with React 18+ and 19+ concurrent rendering.
• gotcha Virtualized lists require their container to have a defined height. If the `Virtuoso` component or its parent does not have an explicit `height` or `max-height` CSS property, the list will not render, or it may render with a `zero-sized element` error.
  Fix: Ensure the `Virtuoso` component or its direct parent has a CSS `height` (e.g., `height: '100%'`, `height: '500px'`) or `max-height` to establish a scrollable viewport. Consider using a flexbox layout for responsive sizing.
• gotcha Applying CSS `margin` to individual list items or their direct children can lead to incorrect scroll height calculations, preventing users from scrolling to the end of the list or causing scroll jumping. Virtuoso uses `ResizeObserver` which reports `contentRect` and does not include margins.
  Fix: Instead of `margin`, use `padding` on the item content or its internal elements to create spacing, or use CSS `gap` on the parent container if applicable. If margins are unavoidable, ensure they do not protrude outside the item container.
• gotcha Complex or slow-rendering content within `itemContent` can cause performance issues (jank) during scrolling, especially with many items or dynamic content like images.
  Fix: Use `React.memo` for the components rendered inside `itemContent` to prevent unnecessary re-renders. Implement simplified placeholders (skeletons) for heavy content while scrolling by hooking into the `isScrolling` callback. Optimize the rendering logic within `itemContent` to be as lightweight as possible.

Install

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

Imports

• Virtuoso
  wrong:

  const Virtuoso = require('react-virtuoso').Virtuoso;

  correct:

  import { Virtuoso } from 'react-virtuoso';

  React Virtuoso primarily uses named exports. CommonJS `require` syntax is not recommended in modern React/ESM projects, especially for libraries built with ESM in mind.
• GroupedVirtuoso
  wrong:

  import GroupedVirtuoso from 'react-virtuoso/grouped';

  correct:

  import { GroupedVirtuoso } from 'react-virtuoso';

  All major components are named exports from the main `react-virtuoso` package. There are no separate entry points for `grouped` or `table` components.
• TableVirtuoso
  wrong:

  import { TableVirtuoso } from 'react-virtuoso/table';

  correct:

  import { TableVirtuoso } from 'react-virtuoso';

  For TypeScript users, type imports like `import type { VirtuosoHandle } from 'react-virtuoso';` are available for component instances.

Quickstart

This quickstart demonstrates a basic `Virtuoso` component rendering a list of 5000 items with simulated variable heights within a fixed-height container, showcasing its core virtualization capabilities.

import { Virtuoso } from 'react-virtuoso';
import React from 'react';

const generateItems = (count: number) =>
  Array.from({ length: count }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
    height: Math.random() * 50 + 50 // Simulate variable heights
  }));

export default function MyVirtualizedList() {
  const items = React.useMemo(() => generateItems(5000), []);

  return (
    <div style={{ height: '400px', border: '1px solid #ccc', margin: '20px' }}>
      <h2 style={{ padding: '10px', margin: 0, background: '#f0f0f0' }}>Large Virtual List Example</h2>
      <Virtuoso
        style={{ height: 'calc(100% - 60px)' }} // Adjust for title height
        totalCount={items.length}
        itemContent={(index) => (
          <div
            style={{
              padding: '15px 10px',
              borderBottom: '1px solid #eee',
              background: index % 2 === 0 ? '#fafafa' : 'white',
              height: items[index].height // Use pre-calculated variable height
            }}
          >
            <strong>{items[index].text}</strong>: This is content for item {index}.
            It demonstrates variable height functionality.
          </div>
        )}
        // Optional: Implement infinite scroll
        // endReached={() => {
        //   console.log('End of list reached, fetching more data...');
        //   // In a real app, you would fetch more items here
        // }}
        // overscan={200} // Render 200px before/after viewport for smoother scroll
      />
    </div>
  );
}