Prepared Docs

Overview

VirtualizedList renders only the visible rows of a very long list to keep scroll performance acceptable—chat histories, log tails, large roster lists. Correct estimateSize and remeasurement strategy prevent scroll jank that would break operator trust in realtime systems. The mental model is "only the rows in view exist in the DOM"; this is a deliberate trade-off that affects find-in-page, keyboard navigation, and third-party DOM tools.

When to use

Thousands of rows where naive mapping drops frames on dispatch workstations.
Append-heavy feeds (live logs, chat) with stable row keys.
Known or estimable row heights, or explicit measure callbacks when dynamic.

When not to use

Short lists (dozens of rows)—use Scrollable with mapped children; it's simpler to debug.
Complex nested expanders with unpredictable heights and no measurement plan—consider pagination or grouped data instead.
Layouts that require full-page find (browser Cmd/Ctrl-F) across the entire list. Virtualization hides offscreen nodes.

Content guidelines

Empty states use the EmptyState pattern with a concrete next step.
aria-posinset / aria-setsize or listbox patterns must remain accurate when virtualization exposes only part of the DOM.

Behavior and states

Row heights. Tune estimateSize to a real average; remeasure on dynamic content expansion.
Append cadence. Debounce high-frequency data appends so scroll anchors don't thrash.
Reverse scroll. Chat patterns with scrollReverse need explicit testing—scroll-to-bottom on new message, preserve position on history fetch.

Best practices

Key rows stably by id, not index, so inserts don't misalign state.
Lazy-render heavy widgets inside rows—profile before mounting them in every row.

Don't

Virtualize inside another scroll container without explicit height constraints.
Mount many stateful components per row when only a fraction are ever visible.

Accessibility

Keyboard navigation must scroll items into view; focus management continues to work with windowing. Announce additions carefully in live regions—high-frequency chat may require batching. See Accessibility for the full contract.

Message for chat row content patterns.
Loading indicator for fetch gaps.

Accessibility / Testing with Screen Readers

Virtualized List / API and Development

Overview

When to use

Thousands of rows where naive mapping drops frames on dispatch workstations.
Append-heavy feeds (live logs, chat) with stable row keys.
Known or estimable row heights, or explicit measure callbacks when dynamic.

When not to use

Short lists (dozens of rows)—use Scrollable with mapped children; it's simpler to debug.
Complex nested expanders with unpredictable heights and no measurement plan—consider pagination or grouped data instead.
Layouts that require full-page find (browser Cmd/Ctrl-F) across the entire list. Virtualization hides offscreen nodes.

Content guidelines

Empty states use the EmptyState pattern with a concrete next step.
aria-posinset / aria-setsize or listbox patterns must remain accurate when virtualization exposes only part of the DOM.

Behavior and states

Row heights. Tune estimateSize to a real average; remeasure on dynamic content expansion.
Append cadence. Debounce high-frequency data appends so scroll anchors don't thrash.
Reverse scroll. Chat patterns with scrollReverse need explicit testing—scroll-to-bottom on new message, preserve position on history fetch.