TanStack / TanStack/virtual

Expose an API to cancel active scroll reconciliation

Open
#1,285 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
7.1k
Forks
466
Avg merge
2d 31m
Merged PRs (30d)
13

Description

Describe the use case

A virtualizer may have a long-distance scrollToIndex reconciliation in progress while the user begins a genuine wheel, touch, pointer, or keyboard scroll. The application must immediately hand viewport ownership back to the user.

In @tanstack/virtual-core 3.17.8, reconcileScroll can continue correcting toward the old target for up to the five-second safety limit. There is no public way to cancel it. The only effective application workaround is a private-field write:

;(virtualizer as unknown as { scrollState: unknown }).scrollState = null

That works, but is intentionally outside the public contract and can silently break on upgrade.

Requested API

A public method such as:

virtualizer.cancelScrollTo()

It should cancel the active scrollToIndex / scrollToOffset reconciliation target without changing the current DOM offset. This lets a user gesture take ownership immediately while preserving normal subsequent measurement compensation.

Why this belongs in core
  • Core owns the reconciliation state and its lifecycle.
  • Consumers cannot reliably infer or cancel every pending internal frame/timer.
  • User input cancellation is needed by chat timelines and other dynamic, long-distance virtual navigation surfaces.
Version

@tanstack/virtual-core 3.17.8; the same private-only state is present on current main.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in the @tanstack/virtual-core implementation around reconcileScroll and the scrollState used by scrollToIndex and scrollToOffset. Trace how the active reconciliation target and its safety limit are managed, then inspect the existing core tests if available. Done means a public cancelScrollTo API stops the active target without changing the current DOM offset and preserves later measurement compensation.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.