fix(react-virtual): make directDomUpdates a no-op without containerRef

[piecyk]

🎯 Changes

Make directDomUpdates a no-op for direct DOM writes when containerRef is omitted. Previously the virtualizer still wrote item positions while never sizing the container (a broken half-state). Now omitting containerRef skips all direct writes while still skipping re-renders, letting consumers own the DOM updates themselves (e.g. in onChange).

✅ 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

  • Fixed direct DOM update behavior when a container reference is not provided; now properly skips all DOM writes instead of partial updates.

• Documentation

  • Updated documentation clarifying direct DOM update behavior without a container reference.

• Tests

  • Added test coverage for direct DOM updates without container reference.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bbebe4b1-f2b9-4057-81ba-868ffae5bffa

📥 Commits

Reviewing files that changed from the base of the PR and between ef69ea3 and 4dd2834.

📒 Files selected for processing (5)

• .changeset/direct-dom-no-container.md
• docs/framework/react/react-virtual.md
• packages/react-virtual/e2e/app/direct-dom-updates/main.tsx
• packages/react-virtual/e2e/app/test/direct-dom-updates.spec.ts
• packages/react-virtual/src/index.tsx

---

📝 Walkthrough

Walkthrough

When directDomUpdates is enabled but containerRef is omitted, applyDirectStyles now returns early before computing getTotalSize() or applying any container/item styles. An e2e test app gains a noContainer query-parameter mode and a new Playwright spec verifies no DOM writes occur while re-renders remain skipped. Documentation and a changeset entry describe the updated behavior.

Changes

directDomUpdates no-op without containerRef

Layer / File(s)	Summary
applyDirectStyles early-return guard packages/react-virtual/src/index.tsx	Broadens the early-return condition to also check state.container, preventing container sizing and item positioning writes when containerRef is absent.
E2E fixture noContainer flag and Playwright test packages/react-virtual/e2e/app/direct-dom-updates/main.tsx, packages/react-virtual/e2e/app/test/direct-dom-updates.spec.ts	Adds a noContainer=1 URL flag that passes undefined as the scroll container ref, and a Playwright test asserting no DOM style writes occur while render-skip semantics are preserved.
Changeset and docs .changeset/direct-dom-no-container.md, docs/framework/react/react-virtual.md	Adds a patch changeset entry and a documentation note clarifying that omitting containerRef disables all direct DOM writes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TanStack/virtual#1180: Introduced the directDomUpdates feature and the applyDirectStyles function that this PR modifies to guard against a missing containerRef.

Poem

🐇 Hop hop, the container's not there,
No styles shall be written—I swear!
With state.container null,
We skip the whole call,
And re-renders? Still skipped! How fair! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: making directDomUpdates a no-op without containerRef, which is the core modification in this PR.
Description check	✅ Passed	The description follows the template structure with completed 🎯 Changes, ✅ Checklist (all items checked), and 🚀 Release Impact sections, providing clear context for the change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 4dd2834

Command	Status	Duration	Result
nx affected --targets=test:sherif,test:knip,tes...	✅ Succeeded	43s	View ↗
nx run-many --target=build --exclude=examples/**	✅ Succeeded	16s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-15 18:57:47 UTC

[pkg-pr-new]

More templates

• @tanstack/virtual-example-angular-dynamic
• @tanstack/virtual-example-angular-fixed
• @tanstack/virtual-example-angular-infinite-scroll
• @tanstack/virtual-example-angular-padding
• @tanstack/virtual-example-angular-smooth-scroll
• @tanstack/virtual-example-angular-sticky
• @tanstack/virtual-example-angular-table
• @tanstack/virtual-example-angular-variable
• @tanstack/virtual-example-angular-window
• tanstack-lit-virtual-example-dynamic
• tanstack-lit-virtual-example-fixed
• tanstack-react-virtual-example-chat
• tanstack-react-virtual-example-dynamic
• tanstack-react-virtual-example-fixed
• tanstack-react-virtual-example-infinite-scroll
• tanstack-react-virtual-example-padding
• tanstack-react-virtual-example-pretext
• tanstack-react-virtual-example-scroll-padding
• tanstack-react-virtual-example-smooth-scroll
• tanstack-react-virtual-example-sticky
• tanstack-react-virtual-example-table
• tanstack-react-virtual-example-variable
• tanstack-react-virtual-example-window
• tanstack-svelte-virtual-example-dynamic
• tanstack-svelte-virtual-example-fixed
• tanstack-svelte-virtual-example-infinite-scroll
• tanstack-svelte-virtual-example-smooth-scroll
• tanstack-svelte-virtual-example-sticky
• tanstack-svelte-virtual-example-table
• tanstack-vue-virtual-example-dynamic
• tanstack-vue-virtual-example-fixed
• tanstack-vue-virtual-example-infinite-scroll
• tanstack-vue-virtual-example-padding
• tanstack-vue-virtual-example-scroll-padding
• tanstack-vue-virtual-example-smooth-scroll
• tanstack-vue-virtual-example-sticky
• tanstack-vue-virtual-example-table
• tanstack-vue-virtual-example-variable

@tanstack/angular-virtual

npm i https://pkg.pr.new/@tanstack/angular-virtual@1201

@tanstack/lit-virtual

npm i https://pkg.pr.new/@tanstack/lit-virtual@1201

@tanstack/react-virtual

npm i https://pkg.pr.new/@tanstack/react-virtual@1201

@tanstack/solid-virtual

npm i https://pkg.pr.new/@tanstack/solid-virtual@1201

@tanstack/svelte-virtual

npm i https://pkg.pr.new/@tanstack/svelte-virtual@1201

@tanstack/virtual-core

npm i https://pkg.pr.new/@tanstack/virtual-core@1201

@tanstack/vue-virtual

npm i https://pkg.pr.new/@tanstack/vue-virtual@1201

commit: 4dd2834