feat(virtual-core): add deferLaneAssignment option by 2wheeh · Pull Request #1115 · TanStack/virtual

2wheeh · 2026-01-08T09:31:00Z

🎯 Changes

resolves #1114

Adds deferLaneAssignment option to defer lane caching until items are measured via measureElement.

#1080 introduced lane assignment caching based on estimateSize for visual stability. However, this broke a core use case for masonry layouts where lane assignments should be based on actual measured sizes, not estimates.

This PR adds a new option deferLaneAssignment (default: false):

When false (default): Current behavior - lanes cached immediately from estimateSize
When true: Lanes are calculated but not cached until first measurement, then cached based on actual sizes

✅ 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 a new deferLaneAssignment option (default: false) to control whether lane assignments are cached immediately or deferred until items are measured for more accurate layout.
Documentation
- Clarified lane assignment behavior and documented the new deferLaneAssignment option and its effect on assignment timing.

changeset-bot · 2026-01-08T09:31:04Z

🦋 Changeset detected

Latest commit: 8496f50

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@tanstack/virtual-core	Patch
@tanstack/angular-virtual	Patch
@tanstack/lit-virtual	Patch
@tanstack/react-virtual	Patch
@tanstack/solid-virtual	Patch
@tanstack/svelte-virtual	Patch
@tanstack/vue-virtual	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Copilot

Pull request overview

Adds a new deferLaneAssignment option to @tanstack/virtual-core to support masonry-style layouts where lane assignment should be derived from measured sizes (via measureElement/resizeItem) rather than estimateSize, while keeping the existing “stable lanes via caching” behavior as the default.

Changes:

Introduces deferLaneAssignment?: boolean (default false) and conditionally skips lane caching until an item has been measured.
Adds tests covering deferred vs immediate lane caching behavior.
Updates API docs and adds a changeset for release.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/virtual-core/src/index.ts	Adds `deferLaneAssignment` option + logic to skip caching lanes for unmeasured items
packages/virtual-core/tests/index.test.ts	Adds regression tests for deferred/immediate lane caching
docs/api/virtualizer.md	Documents new option and clarifies lane caching behavior
docs/api/virtual-item.md	Updates `lane` documentation to mention caching + deferral option
.changeset/loud-insects-itch.md	Publishes the change as a patch release

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/virtual-core/src/index.ts

docs/api/virtual-item.md

…o deps

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/virtual-core/src/index.ts:732

deferLaneAssignment is now part of the memo deps, but toggling it from false → true via setOptions will still keep any existing laneAssignments cached from estimateSize, because getMeasurements prefers cachedLane regardless of deferLaneAssignment. Consider detecting changes to deferLaneAssignment (similar to lanesChangedFlag) and clearing laneAssignments when it changes (at least when switching to true) so the new mode can take effect at runtime.

      this.options.deferLaneAssignment,
    ],
    (count, paddingStart, scrollMargin, getItemKey, enabled, lanes, deferLaneAssignment) => {
      const lanesChanged =
        this.prevLanes !== undefined && this.prevLanes !== lanes

      if (lanesChanged) {
        // Set flag for getMeasurements to handle
        this.lanesChangedFlag = true
      }

      this.prevLanes = lanes
      this.pendingMeasuredCacheIndexes = []

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/api/virtualizer.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

coderabbitai · 2026-03-19T06:50:02Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fff24bc5-2263-4b41-9b2c-a44da19a9d1d

📥 Commits

Reviewing files that changed from the base of the PR and between e71a42b and cf17381.

📒 Files selected for processing (1)

packages/virtual-core/tests/index.test.ts

✅ Files skipped from review due to trivial changes (1)

packages/virtual-core/tests/index.test.ts

📝 Walkthrough

Walkthrough

A new Virtualizer option deferLaneAssignment (default false) was added to defer caching lane assignments until items are measured. Documentation and tests were added/updated; core measurement logic now respects measured vs. estimated sizes when caching lane assignments.

Changes

Cohort / File(s)	Summary
Changeset `\.changeset/loud-insects-itch\.md`	New changeset added documenting `feat(virtual-core): add deferLaneAssignment option` as a patch for `@tanstack/virtual-core`.
Documentation `docs/api/virtual-item.md`, `docs/api/virtualizer.md`	Updated lane assignment docs; added `deferLaneAssignment?: boolean` docs and clarified when lane assignments are cached (immediately using `estimateSize` vs. deferred until `measureElement`).
Core Implementation `packages/virtual-core/src/index.ts`	Added `deferLaneAssignment?: boolean` to `VirtualizerOptions`; threaded option into measurement/memoization logic and changed `getMeasurements` to avoid caching lane assignments for unmeasured items when deferral is enabled.
Tests `packages/virtual-core/tests/index.test.ts`	Added Vitest cases covering lane-caching behavior for `deferLaneAssignment: true` (deferred caching until measurements) and `deferLaneAssignment: false` (immediate caching).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hop and tally lanes with glee,

I wait to measure what each will be,
No guessed heights first — I pause and see,
Then store my lanes where they should be,
A gentle hop, a stable tree 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a deferLaneAssignment option to virtual-core, which is clearly reflected in the changeset, code modifications, and documentation updates.
Description check	✅ Passed	The PR description follows the template structure, includes clear explanation of changes and motivation, includes issue reference, completes all checklist items, and explains the release impact with changeset.
Linked Issues check	✅ Passed	The PR fully addresses issue `#1114` by implementing the deferLaneAssignment option exactly as requested: deferring lane caching until first measurement while preserving backward compatibility with default false behavior.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the deferLaneAssignment feature: core implementation, tests, documentation updates, and changeset file are all in scope for this objective.

_{✏️ 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

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

coderabbitai

🧹 Nitpick comments (1)

.changeset/loud-insects-itch.md (1)
1-5: Consider using minor instead of patch for a new feature.

Adding a new option (deferLaneAssignment) is typically a minor version bump according to semver, since it introduces new functionality. While the default behavior is preserved, this may warrant minor rather than patch depending on your project's versioning conventions.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.changeset/loud-insects-itch.md around lines 1 - 5, The changeset currently
marks '@tanstack/virtual-core' as a patch but adds a new feature
(deferLaneAssignment); update the release type from "patch" to "minor" in this
changeset so the version bump follows semver for new functionality—edit the
changeset frontmatter replacing 'patch' with 'minor' for
'@tanstack/virtual-core' (the changeset file is the one that declares the
package and the release type).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.changeset/loud-insects-itch.md:
- Around line 1-5: The changeset currently marks '@tanstack/virtual-core' as a
patch but adds a new feature (deferLaneAssignment); update the release type from
"patch" to "minor" in this changeset so the version bump follows semver for new
functionality—edit the changeset frontmatter replacing 'patch' with 'minor' for
'@tanstack/virtual-core' (the changeset file is the one that declares the
package and the release type).

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cc9990a2-b929-4bb5-8fee-543be8140f8c

📥 Commits

Reviewing files that changed from the base of the PR and between c939785 and e71a42b.

📒 Files selected for processing (5)

.changeset/loud-insects-itch.md
docs/api/virtual-item.md
docs/api/virtualizer.md
packages/virtual-core/src/index.ts
packages/virtual-core/tests/index.test.ts

…ignment Verify that lane assignments are cached progressively as items are measured and that earlier cached lanes remain stable when later items are measured. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2wheeh · 2026-03-26T05:50:53Z

@piecyk Hi, would love to know if you're open to this feature — and if the API shape needs changes (e.g. boolean vs string union), happy to adjust.

2wheeh added 2 commits January 8, 2026 18:23

feat(virtual-core): add deferLaneAssignment option

cd1956d

chore: add changeset

7a2e014

2wheeh mentioned this pull request Jan 13, 2026

Lane assignments should respect measured sizes, not just estimates #1114

Open

2 tasks

Merge branch 'main' into feat/defer-lane-assign

3501a23

piecyk requested a review from Copilot March 5, 2026 21:20

Copilot started reviewing on behalf of piecyk March 5, 2026 21:20 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

packages/virtual-core/src/index.ts Show resolved Hide resolved

docs/api/virtual-item.md Outdated Show resolved Hide resolved

2wheeh and others added 3 commits March 8, 2026 00:51

fix(virtual-core): include deferLaneAssignment in getMeasurements mem…

581c5c9

…o deps

Update docs/api/virtual-item.md

8b1f8bd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge branch 'main' into feat/defer-lane-assign

2900864

2wheeh requested a review from Copilot March 7, 2026 15:59

Copilot started reviewing on behalf of 2wheeh March 7, 2026 15:59 View session

Copilot AI reviewed Mar 7, 2026

View reviewed changes

docs/api/virtualizer.md Outdated Show resolved Hide resolved

2wheeh and others added 2 commits March 8, 2026 01:06

Update docs/api/virtualizer.md

8496f50

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge branch 'main' into feat/defer-lane-assign

e71a42b

coderabbitai bot reviewed Mar 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(virtual-core): add deferLaneAssignment option#1115

feat(virtual-core): add deferLaneAssignment option#1115
2wheeh wants to merge 9 commits intoTanStack:mainfrom
2wheeh:feat/defer-lane-assign

2wheeh commented Jan 8, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

coderabbitai bot commented Mar 19, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai bot left a comment

Uh oh!

2wheeh commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

2wheeh commented Jan 8, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

coderabbitai bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

2wheeh commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

2wheeh commented Jan 8, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 8, 2026 •

edited

Loading

coderabbitai bot commented Mar 19, 2026 •

edited

Loading