#1285·virtual

Expose an API to cancel active scroll reconciliation

Author: rubinshCreated Sep 13, 2026Updated Sep 13, 2026

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:

typescript
;(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:

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