Adapt default logic to adjust scroll position only on backward scrolling

[balzdur]

This change is based on those issues: #910, #562
It tries to implement the idea from this message:

@kmpeeduwee it's default behaviour, can be disabled using shouldAdjustScrollPositionOnItemSizeChange, please checkout docs https://tanstack.com/virtual/latest/docs/api/virtualizer#shouldadjustscrollpositiononitemsizechange

Overall we should change the logic to adjust position only on scrolling backward.

Originally posted by @piecyk in #910

Disclaimer: I'm not an expert of the lib, neither someone used to contribute a lot to open source (and/or on tanstack repositories). In particular, I do not know if this should be considered breaking (since the default behaviour will change) or not.

[changeset-bot]

🦋 Changeset detected

Latest commit: c7ef283

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit c7ef283.

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

---

☁️ Nx Cloud last updated this comment at 2025-06-09 12:31:09 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-dynamic
• tanstack-react-virtual-example-fixed
• tanstack-react-virtual-example-infinite-scroll
• tanstack-react-virtual-example-padding
• 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@1002

@tanstack/lit-virtual

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

@tanstack/react-virtual

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

@tanstack/solid-virtual

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

@tanstack/svelte-virtual

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

@tanstack/virtual-core

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

@tanstack/vue-virtual

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

commit: c7ef283

[piecyk]

@balzdur Yeah, I think this makes sense as the default behavior. Adjusting the scroll position only during backward scrolling seems more intuitive and prevents unexpected jumps when resizing items. Regarding the breaking change, good question! It technically changes the default behavior, but I believe it's more of a bug fix than a breaking change since the current behavior is often not what users expect.

[balzdur]

Is it ok to merge this or do I need to make some stuff ? 🙂

[piecyk]

@balzdur looks like with this change we broke bidirectional lists, for example, in chat apps where scrolling upward loads older messages. Even without actively scrolling, we should stay in the same place after new elements are loaded. See this related discussion: #1013 (reply in thread)