UIScrollView: scroll event
The scroll event fires when the scroll position changes.
Syntax
scroller.addEventListener('scroll', (event) => { })Event object
Event. It has only type and target (this scroll view) and carries no other data. Not cancelable. Read the position from contentOffset.
When it fires
- User dragging, momentum scrolling after release, writing
contentOffsetfrom code, andsetContentOffset()animations all fire it. - It coalesces. Scrolling that happens while a previous
scrollhas not yet fired does not fire separately. So the number ofscrollevents does not equal the number of position changes; do not use it for counting (measured: three consecutive position writes produced only onescroll). - Writing
contentOffsetbefore the window is shown does not fire it. The position is written and reads back correctly, but no event arrives (verified by testing). - One real swipe lasting 1819 ms fired it 100 times (simulator, Debug build). Reading the position and changing views in the callback is normal usage.
- Fires after the change, once the current JS finishes running. When the callback runs, the scroll view's state is already the new one.
- No overhead without listeners.
Examples
Reading the current position
js
const scroller = new UIScrollView();
scroller.addEventListener('scroll', () => {
console.log(scroller.contentOffset.y);
});Effect: logs a number continuously while scrolling. At the very top it is around 0 (negative with a safe area), and the further down it scrolls the larger it gets, in pt.
Events coalesce
js
const scroller = new UIScrollView();
let count = 0;
scroller.addEventListener('scroll', () => { count += 1; });
scroller.contentOffset = new CGPoint(0, 10);
scroller.contentOffset = new CGPoint(0, 20);
scroller.contentOffset = new CGPoint(0, 30);
console.log(scroller.contentOffset.y);
setTimeout(() => console.log(count), 100);Result: the first line logs 30 immediately; writes take effect synchronously. 100 ms later it logs 1 (verified by testing, with the scroll view in a window already shown). The callback was not called at all while the three assignments ran.
Corresponding iOS API
scrollViewDidScroll: of UIScrollViewDelegate.