fix(virtual-core): invalidate measurements when gap option changes

[2wheeh]

🎯 Changes

resolves #1222

gap was missing from the getMeasurementOptions memo dependencies, so a gap-only option change never invalidated cached measurements.

The list kept the layout computed with the old gap until something else (count change, item resize, remount) recomputed it.

Changes

• Add options.gap to the measurement memo key and thread it through to getMeasurements, replacing the direct this.options.gap reads
• Regression tests: virtual-core (single-lane and multi-lane) and react-virtual (gap change via rerender)

✅ 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.

Summary by CodeRabbit

• New Features
  • Added/recognized an optional spacing gap prop for virtualized lists, so item/row positioning reflects updated gap values.
• Bug Fixes
  • Virtualized measurements now correctly refresh when gap changes, preventing stale cached positions.
  • Total size and lane/row start calculations stay accurate after gap updates.
• Tests
  • Added regression coverage for both single-lane and multi-lane gap changes.
• Chores
  • Added a patch release note calling out that gap changes invalidate measurements.

[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: 30a16b98-f4a4-4731-bffb-b2f2b6494023

📥 Commits

Reviewing files that changed from the base of the PR and between b816cf9 and 1b32928.

📒 Files selected for processing (1)

• packages/virtual-core/src/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/virtual-core/src/index.ts

---

📝 Walkthrough

Walkthrough

Fixes stale virtualizer measurements when gap changes dynamically. Measurement memoization now tracks gap, layout calculations use the updated value, and regression tests cover single-lane, multi-lane, and React rendering behavior. A changeset records a patch release for @tanstack/virtual-core.

Changes

Gap Invalidation Fix

Layer / File(s)	Summary
Memoize gap in measurement options and layout calculations packages/virtual-core/src/index.ts	getMeasurementOptions tracks and returns gap; getMeasurements uses it for single-lane and multi-lane start-offset calculations.
Regression tests, React wiring, and release note packages/virtual-core/tests/index.test.ts, packages/react-virtual/tests/index.test.tsx, .changeset/eighty-ants-slide.md	Tests verify recomputed starts, total size, and rendered transforms after gap changes; the changeset declares a patch release for @tanstack/virtual-core.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• TanStack/virtual#1224: Both changes modify virtual-core multi-lane placement logic, including lane start calculations.

Suggested reviewers: piecyk

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately describes the main change: invalidating measurements when gap changes.
Description check	✅ Passed	The description covers the bug, fix, regression tests, checklist, and release impact, matching the template well.
Linked Issues check	✅ Passed	The code and tests address #1222 by invalidating cached measurements and updating layout/getTotalSize on dynamic gap changes.
Out of Scope Changes check	✅ Passed	The changes are focused on the gap invalidation fix, related tests, and a changeset, with no obvious unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 1b32928

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

---

☁️ Nx Cloud last updated this comment at 2026-07-12 09:31:21 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-marko-virtual-example-dynamic
• tanstack-marko-virtual-example-fixed
• tanstack-marko-virtual-example-grid
• tanstack-marko-virtual-example-infinite-scroll
• tanstack-marko-virtual-example-smooth-scroll
• tanstack-marko-virtual-example-variable
• tanstack-marko-virtual-example-window
• 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@1223

@tanstack/lit-virtual

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

@tanstack/marko-virtual

npm i https://pkg.pr.new/@tanstack/marko-virtual@1223

@tanstack/react-virtual

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

@tanstack/solid-virtual

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

@tanstack/svelte-virtual

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

@tanstack/virtual-core

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

@tanstack/vue-virtual

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

commit: 1b32928