Virtualization

Virtualization

The list component auto-virtualizes when the filtered item count exceeds a threshold (default: 100).

How It Works

1. Detection — When filteredCount > 100, virtualization activates automatically
2. Measurement — ResizeObserver measures actual item heights
3. Windowing — Only visible items + overscan are rendered to the DOM
4. Positioning — Items are positioned with GPU-composited translate transforms
5. Deferred measurement — requestIdleCallback measures items during idle periods

Configuration

<Command.List
  virtualize={true}        // Enable (default: true)
  estimateSize={44}         // Initial estimated height per item
  overscan={8}              // Extra items rendered outside viewport
>
  {items}
</Command.List>

Disabling Virtualization

<Command.List virtualize={false}>
  {/* All items rendered to DOM */}
</Command.List>

CSS Optimization

The library uses these CSS properties for performance:

[data-command-item] {
  content-visibility: auto;
  contain-intrinsic-size: auto 44px;
}

[data-command-list-virtual] {
  position: relative;
  will-change: transform;
}

Performance

Items	Without Virtualization	With Virtualization
100	~2ms render	~2ms render (not activated)
1,000	~20ms render	~3ms render
10,000	~200ms render	~3ms render
100,000	Unusable	~4ms render