v149 · scroll promise · recovery

Scroll Sequencing with Recovery

Build a chapter-by-chapter reader tour. When the user interrupts a scroll mid-flight the promise resolves with { interrupted: true } — the app catches that, shows a recovery bar, and offers to retry the interrupted step or cancel the tour.

Click anywhere inside the reader to interrupt the current scroll.

Chapter 1 · Introduction

Before Chrome 149, there was no reliable way to know when a smooth scroll finished. Developers guessed with setTimeout — always too short or too long.

Chapter 2 · The Promise Shape

scrollTo() now returns a Promise<ScrollResult>. Clean completion resolves to { interrupted: false }. Any interruption resolves to { interrupted: true }.

Chapter 3 · Retry Patterns

When a scroll is interrupted, decide: retry silently, prompt the user, or abort. The choice is fully in your hands — the API gives you the signal, your code provides the policy.

Chapter 4 · Real Applications

Guided onboarding tours, slide shows, and section-reveal animations all benefit from sequential scroll + await. No more polling scrollTop in a loop.

Chapter 5 · Conclusion

The scroll promise turns a fire-and-forget action into a first-class async operation that can be composed, retried, and wired into any flow. That's the upgrade.

Scroll interrupted.
State:idle
Chapter:—
Last result:—
Interrupts:0
Retries:0
async function runTour(reader, chapters) {
  let i = 0;
  while (i < chapters.length) {
    const result = await reader.scrollTo({
      top: chapters[i].offsetTop,
      behavior: 'smooth',
    });

    if (result.interrupted) {
      const resume = await promptUser('Interrupted. Resume?');
      if (!resume) return;   // user cancelled
      // else: retry same chapter (i stays the same)
      continue;
    }

    await highlight(chapters[i]);  // post-scroll animation
    i++;
  }
}

see also