feat(virtual-core): add deferLaneAssignment option

[2wheeh]

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

[changeset-bot]

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

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