The new scroll events introduced in this document provides web developers a way to listen to the state of the scrolling and when their content is being overscrolled or when the scrolling has finished. This information will be useful for the effects such as pull to refresh or history swipe navigations in the web apps.

Introduction

With CSS overscroll behavior property developers can prevent user-agent defined default boundary actions. Overscroll affordance (e.g. rubber-banding or glow effect), pull to refresh, and history swipe navigation are examples of default boundary actions.

Overscroll behavior property lets developers to prevent default aformentioned boundary actions. However in order to implement customized behaviors, they still need to register a combination of scroll, touch, wheel event listeners to find out when overscrolling has started and trigger their customized scroll boundary behavior. This approach has the following disadvantages/limitations:

The overscroll and scrollend events

To simplify overscroll behavior customization we propose firing overscroll and scrollend events.

User agents MUST fire an overscroll event to the scrolling element when it reaches its scrolling extent. In this case the target of such event will be the scrolling element. When no element has consumed any delta in the current scroll sequence the target will be the last element in scroll chain. In the presence of an element with overscroll-behavior-x|y auto the scroll chain is cut and that element will be the last element in the cut chain and get the overscroll event.

User agents MUST fire an scrollend event to the scrolled element indicating that the scroll sequence has ended and any scroll offset changes has been applied (i.e. any active scroll animation has completed). When no element has scrolled during the current scroll sequence the scrollend will get sent to the overscroll event's target.

overscroll
Type overscroll
Interface OverscrollEvent
Sync / Async Async
Bubbles Yes if the target is Document
Trusted Targets Element, Document
Cancelable No
Composed Yes
Default action None
scrollend
Type scrollend
Interface Event
Sync / Async Async
Bubbles Yes if the target is Document
Trusted Targets Element, Document
Cancelable No
Composed Yes
Default action None

Note that similar to scroll event, overscroll and scrollend events bubble if fired at document. Similarly the overscroll and scrollend events are async, non-cancelable, and do not have any default actions. To prevent default boundary actions developers must use CSS overscroll behavior property.

Extensions to the GlobalEventHandlers interface

The following section describes extensions to the existing GlobalEventHandlers interface, defined in [[!HTML5]], to facilitate the event handler registration.

partial interface GlobalEventHandlers {
    attribute EventHandler onoverscroll;
    attribute EventHandler onscrollend;
};
            
onoverscroll
The event handler IDL attribute (see [[!HTML5]]) for the overscroll event type.
onscrollend
The event handler IDL attribute (see [[!HTML5]]) for the scrollend event type.