From e53ac9d7ca8afa6a92d9bf454b98871376b06d50 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 7 Oct 2026 15:39:00 +0000 Subject: [PATCH] docs: explain where scrollTo's final offset is delivered Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LRqiwDiwMREi1PjUC5typh --- docs/api/user-event.md | 6 ++++++ website/docs/14.x/docs/api/events/user-event.mdx | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/docs/api/user-event.md b/docs/api/user-event.md index 7ef87273a..71985ec28 100644 --- a/docs/api/user-event.md +++ b/docs/api/user-event.md @@ -294,6 +294,12 @@ The sequence of events depends on whether the scroll includes an optional moment - `scroll` (multiple events) - `momentumScrollEnd` +### Final scroll offset + +As in native `ScrollView`, the last drag step does not trigger a `scroll` event. A drag-only scroll (no `momentumY` or `momentumX`) delivers the target offset only in `scrollEndDrag`, so `onScroll` never sees it. For example, `scrollTo(scrollView, { y: 100 })` calls `onScroll` with offsets below 100, then calls `onScrollEndDrag` with 100. With momentum, the last `scroll` event and `momentumScrollEnd` both carry the final momentum offset. + +This matters when UI depends on the `onScroll` offset, like sticky headers, "scroll to top" buttons, or paging indicators. To have `onScroll` receive the target offset, add a momentum part, e.g. `scrollTo(scrollView, { y: 50, momentumY: 100 })`. If your component needs the resting position, also handle `onScrollEndDrag` and `onMomentumScrollEnd`, as on a real device. + ## `pullToRefresh()` \ > [!NOTE] diff --git a/website/docs/14.x/docs/api/events/user-event.mdx b/website/docs/14.x/docs/api/events/user-event.mdx index c5e1886b2..49dd95417 100644 --- a/website/docs/14.x/docs/api/events/user-event.mdx +++ b/website/docs/14.x/docs/api/events/user-event.mdx @@ -295,6 +295,12 @@ The sequence of events depends on whether the scroll includes an optional moment - `scroll` (multiple events) - `momentumScrollEnd` +### Final scroll offset {#scroll-final-offset} + +As in native `ScrollView`, the last drag step does not trigger a `scroll` event. A drag-only scroll (no `momentumY` or `momentumX`) delivers the target offset only in `scrollEndDrag`, so `onScroll` never sees it. For example, `scrollTo(scrollView, { y: 100 })` calls `onScroll` with offsets below 100, then calls `onScrollEndDrag` with 100. With momentum, the last `scroll` event and `momentumScrollEnd` both carry the final momentum offset. + +This matters when UI depends on the `onScroll` offset, like sticky headers, "scroll to top" buttons, or paging indicators. To have `onScroll` receive the target offset, add a momentum part, e.g. `scrollTo(scrollView, { y: 50, momentumY: 100 })`. If your component needs the resting position, also handle `onScrollEndDrag` and `onMomentumScrollEnd`, as on a real device. + ## `pullToRefresh()` \{#pull-to-refresh} :::note