GeezerVison

The new scroll events introduced in this document provide 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:

• Needs to be implemented for different methods of scrolling separately (touchscreen, wheel, keyboard, etc.)
• If the developer wants to trigger overscroll animation at the end of the scroll gesture, touchend event listener can be used for touchscreen scrolling. However for other methods of scrolling (e.g. touchpad scrolling) this won’t be possible using the currently existing events.
• In presence of a cross origin iframe the embedder that might get scrolled might not get the touchmove/wheel events at all.

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.

dictionary OverscrollEventInit : EventInit {
  double deltaX = 0.0;
  double deltaY = 0.0;
};
interface OverscrollEvent : Event {
    readonly attribute double deltaX;
    readonly attribute double deltaY;
};
      

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

partial interface GlobalEventHandlers {
    attribute EventHandler onoverscroll;
    attribute EventHandler onscrollend;
};