CSS Overscroll Behavior Module Level 2

1. Introduction

This module defines CSS features relating to scroll chaining, boundary default actions, and overscroll areas positioned beyond the scroll boundary of a container. It supersedes and extends [CSS-OVERSCROLL-1], and is organized into the following sections:

Overscroll Containers and Areas

Defines overscroll containers, overscroll areas, the overscroll-container-type property, the :overscroll-open and :overscroll-closed pseudo-classes, and the ::overscroll-backdrop pseudo-element.

The Box Model

Defines the anonymous overscroll area parent scroll container box, out-of-flow positioning and mandatory scroll snapping of overscroll areas, painting order, and push vs. overlay translation.

Scroll Chaining and Boundary Default Actions and Overscroll Behavior Properties

Defines scroll chaining, the scroll chain order for overscroll containers and overscroll areas, boundary default actions, and the overscroll-behavior property and its physical and flow-relative longhands.

Overscroll Events

Defines the OverscrollEvent interface and the overscrollstart, overscrollchanging, overscrollend, and overscrollcancel events.

Appendix A: HTML Specification Changes

Defines the HTML overscrollcontainer and overscrollarea attributes, the toggle-overscroll, show-overscroll, and hide-overscroll command invokers, container-scoped inert rules, and GlobalEventHandlers additions.

1.1. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

1.2. Module Interactions

This module extends scrolling and overflow concepts defined in [CSS-OVERFLOW-3], [CSS-SCROLL-SNAP-1], [CSS-SCROLL-SNAP-2], [CSS-POSITION-4], and [CSSOM-VIEW-1].

2. Overscroll Containers and Areas

A common UI pattern is to have large but rarely-needed UI elements, such as nav lists, be displayed "off-screen" at first, and then revealed either by scrolling in that direction or by activating some "reveal" button. Designing this pattern correctly, with all accessibiilty considerations taken care of, is fairly complicated to do by hand and requires scripting; the overscroll container and overscroll area concepts defined here handle all of this automatically for the author, making this pattern very easy to use correctly.

If an element is defined as an overscroll container, some of its children can be defined as overscroll areas, which wraps them in an anonymous scroll container sized to the overscroll container, and makes them absolutely positioned so they can be initially positioned "outside" of the overscroll container, hiding them from view. They’re then revealed (or hidden) by overscroll behavior on the overscroll container, or by dedicated command invokers, which scroll them into view or back to their original position.

Overscroll areas can additionally be styled with the :overscroll-open or :overscroll-closed pseudo-classes, and have an ::overscroll-backdrop pseudo-element which is displayed while the overscroll area is "open" (similar to the ::backdrop pseudo-element that accompanies fullscreen elements).

2.1. Overscroll Containers

An overscroll container is an element that:

1. Generates a principal box whose inner display type is not table, and that is neither an internal table box, an internal ruby box, nor a non-atomic inline-level box; and

2. Is a potential overscroll container, as defined by the host language. (In HTML, this is an element with the overscrollcontainer attribute; see Content and IDL Attributes); and

3. Has a computed overscroll-container-type other than none.

Note: An overscroll container does not have to be a scroll container (its overflow may be visible).

2.2. Overscroll Areas

An element area is an overscroll area if all of the following are true:

1. area is a potential overscroll area as defined by the host language (In HTML, this is an element with the overscrollarea attribute; see Content and IDL Attributes); and

2. area’s flat tree parent element is an overscroll container in the same tree scope as area; and

3. area is not in the top layer; and

4. area is the target of at least one show invoker or toggle invoker in the same tree scope as area (see Command Invokers).

If any of these conditions ceases to hold, area ceases to be an overscroll area and is laid out as an ordinary child of its parent.

Opening an overscroll area brings the overscroll area into its overscroll container’s scrollport by scrolling its overscroll area parent, whether via user scroll chaining or by activating an overscroll invoker.

2.3. The overscroll-container-type Property

The overscroll-container-type property specifies whether a potential overscroll container establishes an overscroll container, and how opening its overscroll areas affects the container’s content.

auto

Behaves as push.

Note: The definition of auto may change as usage experience is gained.

push

The element can establish an overscroll container. Opening an overscroll area both shifts the overscroll area into view, and shifts the container’s content the same way to avoid overlap. (See § 3.4 Stacking and Push Translation.)

overlay

The element can establish an overscroll container. Opening an overscroll area shifts only the overscroll area, overlaying it on top of the stationary container content. (See § 3.4 Stacking and Push Translation.)

none

The element does not establish an overscroll container.

<button commandfor="drawer" command="toggle-overscroll">Menu</button>
<div id="container" overscrollcontainer>
  <nav id="drawer" overscrollarea>...</nav>
  <main>...</main>
</div>

#container {
  overscroll-container-type: overlay;
  overflow: auto;
}
#drawer {
  right: 100%;
  width: 250px;
  height: 100%;
}
@media (min-width: 900px) {
  #container {
    overscroll-container-type: none;
    display: grid;
    grid-template-columns: 250px auto;
  }
}

2.4. The :overscroll-open and :overscroll-closed Pseudo-Classes

The :overscroll-open pseudo-class matches an overscroll area whose overscroll area parent is in the overscrolling state (see § 6.1 Event Dispatch).

The :overscroll-closed pseudo-class matches an overscroll area whose overscroll area parent is not in the overscrolling state.

Note: An element that is not a valid overscroll area (for example, when its parent has overscroll-container-type: none or when it lacks a valid show invoker or toggle invoker) matches neither :overscroll-open nor :overscroll-closed.

2.5. The ::overscroll-backdrop Pseudo-Element

Each overscroll area originates a ::overscroll-backdrop fully styleable pseudo-element.

When generated, the ::overscroll-backdrop box is a child of its originating element’s overscroll area parent, painted immediately behind the overscroll area. Its containing block is the fixed containing block of the overscroll area parent, so it remains aligned with that overscroll area parent’s scrollport rather than scrolling with the overscroll area.

Note: Because ::overscroll-backdrop uses the fixed containing block of its own overscroll area parent, scrolling that overscroll area parent to open its overscroll area does not move the backdrop. However, in push mode, if another overscroll area higher in the stack is opened, that higher overscroll area parent’s scroll translation shifts this overscroll area parent and its ::overscroll-backdrop along with the rest of the underlying content.

3. The Box Model

3.1. Containment and Clipping on the Overscroll Container

An overscroll container establishes layout containment (as if contain: layout were applied) and clips its overscroll area parent boxes to its padding box.

3.2. The Overscroll Area Parent Box

For each overscroll area area of an overscroll container container, the user agent generates an anonymous scroll container box called area’s overscroll area parent:

1. area’s overscroll area parent is a layout child of container’s principal box. It is out-of-flow positioned (position: absolute, inset: 0, display: block) with container’s fixed containing block as its containing block.

2. The overscroll area parent establishes a scroll container (overflow: auto, scrollbar-width: none, pointer-events: none) that inherits overscroll-behavior and scroll-behavior from area. Unlike standard scroll containers, its scrollable overflow area is not clamped at the scroll origin; it extends in all four physical directions (top, left, bottom, right) to enclose both its local containing block origin ((0, 0) of size equal to container’s scrollport) and area’s border box.

3. area’s ::overscroll-backdrop box and area’s principal box are reparented as the children of area’s overscroll area parent, in that order.

Note: The overscroll area parent can be implemented as a non-exposed pseudo-element originating on the overscroll area (which inherits overscroll-behavior and scroll-behavior from the overscroll area), subject to the box tree reparenting above.

3.3. Positioning and Snapping of Overscroll Areas

Every overscroll area area is laid out and snapped within its overscroll area parent scroller as follows:

1. If area’s specified position is not absolute or fixed, its computed position is absolute. If area’s specified display is contents, its computed display is block; otherwise its display is blockified. area’s containing block is scroller’s local containing block.

2. scroller is a scroll snap container (scroll-snap-type: pair mandatory) that ignores scroll-snap-align on descendants and establishes two scroll snap areas:

   • An initial scroll snap area equal to the rectangle of scroller’s scrollport at scroll offset (0, 0), with scroll-snap-align: center and scroll-snap-stop: always. This is scroller’s initial scroll position.

   • A target scroll snap area equal to area’s border box, with scroll-snap-align: center and scroll-snap-stop: normal.

Note: Defining mandatory scroll snap areas at the initial scroll position and at the overscroll area ensures that scrolling settles with the overscroll area either fully open or fully closed, rather than stopping partway in between.

3.4. Stacking and Push Translation

When an overscroll container container has overscroll areas area₁, area₂, …, area_n in flat tree order, with corresponding overscroll area parent boxes scroller₁, scroller₂, …, scroller_n:

1. All overscroll area parent boxes of container are stacked and painted after container’s in-flow and positioned descendants, in reverse flat tree order: scroller_n paints first (immediately above container’s regular content), followed by scroller_n−1, …, scroller₁, with scroller₁ painting last (on top of all other content in container).

   Note: The stacking order is the reverse of the dom order so that when a user scrolls these areas into view the earlier element and its backdrop is visible above the earlier scrolled into view area.

2. Transform hierarchy:

   • If container’s computed overscroll-container-type is overlay, each scroller_k’s scroll translation applies only to scroller_k’s own children (area_k’s ::overscroll-backdrop and area_k).

   • If container’s computed overscroll-container-type is push or auto, each scroller_k’s scroll translation also applies to scroller_k+1 … scroller_n and to container’s content (offset by scroller_k’s scroll origin). Consequently, scrolling scroller_k translates container’s regular content and any lower overscroll areas by the same scroll offset.

3.5. Default UA Stylesheet

Each overscroll area parent is styled as if the following declarations were applied:

display: block;
position: absolute;
inset: 0;
overflow: auto;
overscroll-behavior: inherit;
pointer-events: none;
scroll-behavior: inherit;
scroll-snap-type: pair mandatory;
scrollbar-width: none;

User agents must apply the following default stylesheet rules for overscroll areas and ::overscroll-backdrop:

:overscroll-closed {
  interactivity: inert;
}

::overscroll-backdrop {
  display: none;
  position: absolute;
  inset: 0;
  background-color: light-dark(alpha(from black / .1), alpha(from white / .1));
}

:overscroll-open::overscroll-backdrop {
  display: block;
}

4. Scroll Chaining and Boundary Default Actions

4.1. Scroll Chaining Order

Scroll chaining is when scrolling is propagated from one scroll container to an ancestor scroll container following the scroll chain. Chaining occurs when a scroll container’s scrollport has reached its scroll boundary.

Scroll boundary refers to when the scroll position of a scroll container reaches the edge of the scrollport. If a scroll container (or overscroll container) has no potential to scroll because it does not overflow in the direction of the scroll, it is always considered to be at the scroll boundary. A single-axis scroll container only has a scroll boundary in its scrollable axis; if the scroll is in its other axis, this element is not part of the scroll chain unless it is an overscroll container with an overscroll area parent scrollable in that axis.

A scroll chain is the order in which scrolling is propagated from one scroll container to another:

1. For an overscroll container container with overscroll areas area₁, area₂, …, area_n in flat tree order and corresponding overscroll area parent boxes scroller₁, scroller₂, …, scroller_n, the scroll parent links between container and container’s nearest ancestor scroll container ancestor are ordered as:

   container → scroller_n → scroller_n−1 → … → scroller₁ → ancestor

   Consequently:

   • A scroll reaching the scroll boundary of container chains in reverse flat tree (Last-In, First-Out) order: first to scroller_n (the last overscroll area in flat tree order), then to scroller_n−1, and so on up to scroller₁, before chaining to ancestor.

   • A scroll originating within area_k (or on area_k’s ::overscroll-backdrop) chains to scroller_k, then to scroller_k−1, …, scroller₁, and then to ancestor.

2. For any other scroll container, the next link in its scroll chain is the nearest ancestor scroll container (or overscroll container) in the containing block chain that is scrollable in the scroll’s axis.

3. The viewport participates in scroll chaining as the document’s scrollingElement.

Boundary default action refers to the user-agent-defined default action performed when scrolling against the edge of the scrollport. A local boundary default action is a boundary default action which is performed on the scroll container without interacting with the page, for example displaying a overscroll UI affordance or overscroll area. Conversely, a non-local boundary default action interacts with the page, for example scroll chaining to an ancestor scroll container or a navigation action.

5. Overscroll Behavior Properties

The overscroll behavior controls the permitted boundary default action for a scroll container or overscroll container when its scrollport reaches its scroll boundary.

The overscroll-behavior property specifies the overscroll behavior for a scroll container element. It allows the content author to specify that a scroll container element must prevent scroll chaining and/or overscroll affordances.

An element that is neither a scroll container nor an overscroll container must accept but ignore overscroll-behavior. This property must be applied to all scrolling methods supported by the user agent.

Note: This property should provide guarantees that are, at least, as strong as preventDefault for preventing both scroll chaining and overscroll. Doing otherwise would cause content authors to use preventDefault instead.

5.1. The overscroll-behavior Shorthand

The overscroll-behavior property is a shorthand property that sets the specified values of overscroll-behavior-x and overscroll-behavior-y in that order. If only one value is specified, the second value defaults to the same value.

Values have the following meanings:

contain

This value indicates that the element must not perform non-local boundary default actions such as scroll chaining or navigation. The user agent must not perform scroll chaining to any ancestors along the scroll chain regardless of whether the scroll originated at this element or one of its descendants. This value must not modify the behavior of how local boundary default actions should behave, such as showing any overscroll affordances.

none

This value implies the same behavior as contain and in addition this element must also not perform local boundary default actions such as showing any overscroll affordances.

chain

This value indicates that the element may perform non-local boundary default actions such as scroll chaining or navigation. However, the element must not perform local boundary default actions, such as showing any overscroll affordances.

auto

This value indicates that the user agent should perform the usual boundary default action with respect to scroll chaining, overscroll and navigation gestures.

Note: In the case where a user agent does not implement scroll chaining and overscroll affordances, these values will have no side effects for a compliant implementation.

Note: Programmatic scrolling is clamped and can not trigger any boundary default actions.

5.2. Overscroll and Positioned Elements

This specification does not generally dictate what, if any, "overscroll" or similar actions might occur as a local boundary default action.

However, if a user agent does use "overscroll" behavior (that is, allowing a scrollable element to be scrolled slightly "past the end" of its scrollable area, usually with a "rubber-banding" effect after the scroll or drag is completed), then the following applies:

If an element uses fixed positioning and is positioned relative to the initial containing block, or is a sticky positioned element which is currently stuck to the viewport, then when the root scroller experiences "overscroll", that element must not overscroll with the rest of the document’s content; it must instead remain positioned as if the scroller was at its minimum/maximum scroll position, whichever it will return to when the overscroll is finished.

Even tho this can visually shift the fixed/sticky element relative to other elements on the page, it must be treated purely as a visual effect, and not reported as an actual layout/position change to APIs such as getBoundingClientRect().

Note: This behavior is because fixpos and viewport-stuck stickypos elements are positioned relative to "the viewport", which is conceptually above the root scroller in the page hierarchy (effectively, it’s the scroll container holding the root scroller). Thus, overscrolling the root scroller shouldn’t have any effect on them, just like how an abspos that is a child of a scroller but whose abspos containing block is above the scroller isn’t affected by the scroller doing anything at all, including overscroll.

5.3. Physical Longhands for overscroll-behavior

The overscroll-behavior-x property specifies the overscroll behavior in the horizontal axis and the overscroll-behavior-y property specifies the overscroll behavior in the vertical axis. When scrolling is performed along both the horizontal and vertical axes at the same time, the overscroll behavior of each respective axis should be considered independently.

5.4. Flow-relative Longhands for overscroll-behavior

These properties correspond to the overscroll-behavior-x and overscroll-behavior-y properties. The mapping depends on the element’s writing-mode.

6. Overscroll Events

6.1. Event Dispatch

Each overscroll area area has a boolean overscrolling state (initially false) and a boolean active overscroll flag (initially false).

OverscrollEvents do not bubble and are not cancelable.

6.2. The OverscrollEvent Interface

dictionary OverscrollEventInit : EventInit {
  Element? overscrollTarget = null;
  boolean overscrolling = false;
};

[Exposed=Window]
interface OverscrollEvent : Event {
  constructor(DOMString type, optional OverscrollEventInit eventInitDict = {});
  readonly attribute Element? overscrollTarget;
  readonly attribute boolean overscrolling;
};

overscrollTarget, of type Element, readonly, nullable

The overscroll area Element associated with the event.

overscrolling, of type boolean, readonly

The overscrolling state of overscrollTarget when the event was queued (false when snapped/snapping to the initial scroll position, true when snapped/snapping to overscrollTarget).

7. Accessibility Considerations

Gesture-based overscroll interactions are inaccessible when they lack an equivalent non-gesture control or when offscreen content remains in the sequential focus order. This specification addresses both requirements through the following mechanisms:

• Requiring a show invoker or toggle invoker in the same tree scope as a prerequisite for an element to be a valid overscroll area ensures that every gesture-driven overscroll area has an associated semantic command invoker in the DOM:

  • Keyboard users can navigate to the invoker and activate it to open or close the overscroll area.

  • Screen readers and other assistive technologies perceive a standard activatable button relationship rather than an invisible gesture zone, and authors can apply standard ARIA attributes to the invoker and overscroll area as needed.

  • The invoker provides a discoverable visual affordance for the overscroll action.

• Applying interactivity: inert to closed overscroll areas (:overscroll-closed) removes their interactive descendants from sequential focus navigation while closed:

  • WCAG 3.2.1 On Focus requires that receiving focus must not initiate a change of context. If interactive elements inside a closed overscroll area remained focusable, focusing them would scroll them into view (to satisfy WCAG 2.4.11 Focus Not Obscured) and inadvertently open the overscroll area. Making closed overscroll areas inert prevents focus traversal from triggering this unexpected context change.

  • Allowing a toggle invoker inside its closed overscroll area to escape :overscroll-closed inertness allows a peeking toggle control to remain focusable and operable in both the open and closed states.

8. Security Considerations

There are no known security impacts of this feature. The feature may be used to prevent certain native UI features such as overscroll affordances and overscroll navigations (e.g., pull-to-refresh, swipe navigations). However, this does not expose any additional abilities beyond what is already possible in the platform e.g., by preventing the default action of the event that would cause a scroll.

9. Privacy Considerations

No new privacy considerations have been reported on this specification.

Appendix A: HTML Specification Changes

Content and IDL Attributes

The following boolean content attributes are added to HTML elements:

overscrollcontainer

Designates an element as a potential overscroll container.

overscrollarea

Designates an element as a potential overscroll area.

partial interface HTMLElement {
  [CEReactions, Reflect] attribute boolean overscrollContainer;
  [CEReactions, Reflect] attribute boolean overscrollArea;
};

Command Invokers

An overscroll invoker is a command invoker element whose commandfor target is an overscroll area in the same tree scope and whose command attribute is one of the following keywords:

toggle-overscroll (a toggle invoker)

If the target overscroll area matches :overscroll-open, close the overscroll area; otherwise open the overscroll area.

show-overscroll (a show invoker)

Open the overscroll area.

hide-overscroll (a hide invoker)

Close the overscroll area.

Inertness

A closed overscroll area (matching :overscroll-closed) is made inert by the user agent default stylesheet via interactivity: inert (see § 3.5 Default UA Stylesheet), allowing authors to override the closed interactivity using the interactivity property.

In addition, an element node inside an overscroll container container is subject to the following inert rules:

1. If node is an overscroll area of container that matches :overscroll-open, and another overscroll area of container preceding node in flat tree order also matches :overscroll-open, node and its flat tree subtree are inert.

2. If any overscroll area of container matches :overscroll-open, every flat tree child of container that is not an overscroll area (and its flat tree subtree) is inert.

3. If node is a toggle invoker or show invoker whose target is an overscroll area area of container in the same tree scope, and node is a flat tree descendant of area, then while area matches :overscroll-closed, node (and its flat tree subtree) escapes the interactivity: inert of area, provided container itself is not inert and no overscroll area of container preceding area in flat tree order matches :overscroll-open.

Note: Allowing a toggle invoker to escape the inertness of its closed overscroll area enables patterns where the toggle button is a child of the overscroll area that visually peeks into the overscroll container’s scrollport while the area is closed, remaining interactive so the user can activate it to open the area.

Focus and Light Dismiss

• Activating an overscroll invoker does not change the focused element. Sequential focus navigation (Tab and Shift+Tab) follows from the inert state defined in Inertness and HTML’s sequential focus navigation starting point when a focused element becomes inert.

• The default action of a click event on an ::overscroll-backdrop pseudo-element is to close the overscroll area for every overscroll area of its overscroll container.

Event Handlers

The following event handlers (and their corresponding event handler event types) must be supported by all HTML elements as both event handler content attributes and event handler IDL attributes on GlobalEventHandlers, and by all Document and Window objects as event handler IDL attributes:

partial interface mixin GlobalEventHandlers {
  attribute EventHandler onoverscrollstart;
  attribute EventHandler onoverscrollchanging;
  attribute EventHandler onoverscrollend;
  attribute EventHandler onoverscrollcancel;
};