[ListVirtualizer] Create the virtualizer component

[michaldudak]

An alternative virtualizer implementation to #5173.

The windowing engine from that PR is unchanged — measurement, scroll correction, adaptive estimates, scrollport padding, all of it. What differs is the public API: instead of a <Combobox.Virtualizer> part, the virtualizer itself becomes a standalone <ListVirtualizer> component exported from @base-ui/react/list-virtualizer.

This branch contains #5173, so the diff against master includes that work. To review only what is different:

git diff combobox-virtualization..list-virtualizer-component

API

import { ListVirtualizer } from '@base-ui/react/list-virtualizer';

<Combobox.List>
  <ListVirtualizer getItemKey={(item) => item.id}>
    {(item) => <Combobox.Item value={item}>{item.name}</Combobox.Item>}
  </ListVirtualizer>
</Combobox.List>

Lists publish a virtualization host through context, and <ListVirtualizer> binds to it and windows the collection directly. Combobox keeps its own store wiring, while a single public component serves any list that opts in: it already works inside <Autocomplete.List> (covered by a test), and Select can join by publishing its own host rather than by adding another part.

The props that only make sense to a list implementation — rows, renderRow, apiRef, pinnedRowIndex, scrollToRowIndex, restoreViewportVersion, onUnconstrainedHeight, totalSizeCssVariable — are no longer public; the component derives them from its host. The public surface is children, getItemKey, estimatedItemHeight, overscanPx, enabled, and actionsRef.

Rendering it outside a list that supports virtualization throws, since there is no collection to window.

Supporting the virtualizer in a list

A list opts in through three pieces: the root owns a registry, the list publishes two contexts, and the item consumes per-row metadata. Combobox does all three; Select would follow the same steps without touching ListVirtualizer itself.

1. Root — own the registry

const virtualizationRegistry = useRefWithInit(createListVirtualizationRegistry).current;

Keep it in the root's store. It is how the root learns that a virtualizer is mounted and hands scrolling over to it:

• registry.virtualizer.resetScroll() when filtering, instead of resetting the list element directly.
• registry.virtualizer.getRowMetrics(index) for the geometry of rows that are not mounted.
• scrollItemIntoView: () => registry.virtualizer?.enabled !== true — a mounted but disabled virtualizer renders the whole collection, so the DOM scrollIntoView that static lists rely on has to stay on until the virtualizer actually owns the scroll position.

2. List — publish two contexts

<ListVirtualizationHostContext.Provider value={virtualizationHost}>
  <ListVirtualizationListStateContext.Provider value={virtualizationListState}>
    {element}
  </ListVirtualizationListStateContext.Provider>
</ListVirtualizationHostContext.Provider>

ListVirtualizationHost carries the wiring and must be stable — memoize it on the store:

Field	Purpose
componentName	Part namespace used in diagnostics — Combobox produces <Combobox.Item>, <Combobox.Root>
registry	The registry the root created
virtualItemContext	The list's own React context, through which the virtualizer passes per-row metadata to <Item>
warnUnsupportedConfiguration	Dev-only. Warns about configurations the list cannot window, in its own vocabulary. Called only while a virtualizer is mounted, so a windowable list says nothing

ListVirtualizationListState carries everything reactive, and is re-created whenever a member changes:

Field	Purpose
items	The flat, ordered collection to window
activeIndex	Row kept mounted even when it scrolls outside the window
scrollActiveIntoView	Whether to also scroll to it — false for pointer highlights, which would otherwise move the list under the cursor
renderAllRows	The list temporarily needs every row mounted (browser autofill)
renderAllRowsRestoreVersion	Incremented when such a pass ends, so a virtualizer that mounts afterwards still restores its viewport

The contract is deliberately scoped to flat collections: any list whose rows are a single ordered sequence can implement it, while hierarchical collections need a virtualizer of their own. Nothing in it is Combobox-specific, so a Listbox or Feed could publish the same host without changes to ListVirtualizer.

The split between the two is load-bearing. <Item> reads the host context to detect that it is inside a list, and context updates pierce React.memo. Putting the reactive state in the host would re-render every mounted item on every arrow key. Keeping the host stable means a highlight change re-renders only <ListVirtualizer>.

Reading the highlight in the list costs nothing extra in Combobox, because listProps already carries aria-activedescendant and re-renders it on each highlight change anyway.

3. Item — consume the row metadata

The item reads the context the host published and merges what the virtualizer supplies:

const virtualItem = React.useContext(ComboboxVirtualItemContext);

// The virtualizer knows the logical index; `index` stays a prop for static and external rows.
const explicitIndex = virtualItem?.index ?? indexProp;

// `virtualItem.props` supplies aria-posinset, aria-setsize and data-index.
useRenderElement('div', componentProps, {
  props: [itemProps, virtualItem?.props, defaultProps, elementProps],
});

Two dev-only hooks complete it: useVirtualItemDiagnostics (warns when a virtualized item is disabled without isItemDisabled on the root) and useNonVirtualizedItemRegistration (catches static items rendered alongside the virtualizer, in either mount order).

The windowing tests exercise this contract against a ~60-line synthetic host rather than Combobox, which is the check that it is implementable outside the components that ship with it.

Tradeoffs

• Discoverability. Combobox.Virtualizer showed up in the namespace, the anatomy, and the Combobox API reference. ListVirtualizer needs a separate import and its own docs page. The anatomy snippet and the virtualization section both link to it to compensate.
• Consistency. Everything else inside a Combobox tree is Combobox.*; this is the sole exception.
• Misuse is caught at runtime, not by types.

Docs

New List Virtualizer page under Utils covering anatomy, item rendering, styling, sizing, disabled items, scrollToIndex, and third-party virtualizers. The Combobox page, both demo variants, and the virtualizer experiment are updated. It has no demo of its own — it links to the Combobox virtualized demo rather than duplicating it.

🤖 Generated with Claude Code

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@5414
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@5414
  

commit: e0fae07

[code-infra-dashboard]

Bundle size

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+59.3KB(+13.20%)	🔺+19KB(+12.99%)

Details of bundle changes

Performance

Total duration: 1,238.12 ms -94.60 ms^(-7.1%) | Renders: 78 ⁽⁺⁰⁾ | Paint: 1,943.73 ms -159.48 ms^(-7.6%)

Test	Duration	Renders
Mixed surface mount (app-like density)	65.15 ms ▼-18.54 ms(-22.2%)	5 (+0)

14 tests within noise — details

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	e0fae07
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6a71e22b25c28500083bf076
😎 Deploy Preview	https://deploy-preview-5414--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.