🎯 Changes

Drives useVirtualizer / useWindowVirtualizer re-renders through useSyncExternalStore instead of a useReducer bump. The public API, the returned instance and its identity semantics are unchanged — consumers keep calling getVirtualItems() / getTotalSize() on the instance.

This is the direction suggested in #851 ("useSyncExternalStore feels like a more natural fit compared to useMemo"), applied to the existing hooks rather than as a separate hook: no new hook names, no API change, and nothing that tries to work around React Compiler's knownIncompatible entry for useVirtualizer.

It is the minimal alternative to #1241 (which adds separate useVirtualizerSnapshot hooks). Both are open on purpose so you can pick the shape you prefer — they don't have to be exclusive, see the React Compiler note below.

Design

• Store: a tiny external store whose snapshot is a version counter, bumped by every notification the adapter decides to render (directDomUpdates gating is untouched). The counter tells React that the instance moved; consumers still read render-facing values from the instance.
• useFlushSync preserved: the synchronous scroll path notifies inside flushSync, so the DOM still updates before the scroll handler returns.
• Before-paint catch-up: useSyncExternalStore subscribes in a passive effect, so notifications raised while React is committing — the initial rect/offset measurement in _willUpdate, scroll-element swaps, measureElement refs for freshly mounted items — have no listener yet and would only surface via the store's post-commit check, i.e. after paint (a visible flash of the unmeasured range on heavy initial renders). A final layout effect compares the store version with the rendered one and dispatches a reducer so those still re-render synchronously before paint, exactly as before. Mount / measure render counts in the existing tests are unchanged (2 and 3).
• Shim: use-sync-external-store/shim (React's official package) keeps the ^16.8 || ^17 || ^18 || ^19 peer range; on React 18+ it is React.useSyncExternalStore.
• SSR: getServerSnapshot provided; renderToString covered by a test.

Why

• Under concurrent rendering (transitions, Suspense, useDeferredValue) a reducer bump scheduled while a render is in progress lets React finish and commit that render with the stale range it already read, then re-render. With useSyncExternalStore React checks the store at the end of a non-blocking render and re-renders synchronously if it moved, so a torn frame is never committed.
• The virtualizer is an external mutable store read during render; useSyncExternalStore is the primitive React provides for that.

Tests

• Existing suite unchanged and passing.
• New: scroll notifications through the store (range + isScrolling flip), useFlushSync sync commit vs. React-scheduled commit outside act, SSR via getServerSnapshot, StrictMode, no updates after unmount.
• pnpm run test:pr locally: eslint, types, lib, build/publint, sherif, knip, and the full react-virtual Playwright suite (33 tests, incl. react-compiler and direct-dom-updates).

Note on React Compiler / knownIncompatible

React Compiler ships a hardcoded knownIncompatible entry for @tanstack/react-virtual's useVirtualizer and skips every component that calls it (#1119). This PR deliberately does not change that, and doesn't try to work around it:

• The skip is keyed on the import name, and the returned instance stays identity-stable by design, so a compiled consumer would still memoize getVirtualItems() on it (React Compiler: useVirtual results are cached at their initial values #736, React 19 issue with useWindowVirtualizer #743). The entry stays accurate for now; this PR only changes how the adapter subscribes.
• What it does do is put the adapter on the primitive the compiler story needs — a real store with a snapshot — so the remaining gap is purely the shape of the render-facing values, not the subscription mechanism.

Possible follow-ups, as separate PRs, whichever you prefer:

1. Alias hook — a companion built on the same store that returns the render-facing values as immutable data (virtualItems, totalSize) next to the stable instance for imperative calls. feat(react-virtual): add useVirtualizerSnapshot for React Compiler compatibility via useSyncExternalStore #1241 is one concrete shape of that; it can be rebased onto this store.
2. Upstream delisting — once a compiler-safe contract exists, work with the React team to drop (or narrow) the knownIncompatible entry, so consumers compile without renaming imports.

Refs: #851, #736, #743, #1119, #1241

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes
  • Improved rendering consistency for virtualized content during concurrent rendering.
  • Ensured updates are applied synchronously when needed, reducing visual inconsistencies before paint.
  • Improved reliability across server-rendered, Strict Mode, and unmounted component scenarios.
• Compatibility
  • Preserved existing virtualizer APIs and React 16.8+ support.