Skip to content
Tutorials Center
My learning

Topics

Lesson 68 of 139 ยท Layout Fundamentals

overscroll-behavior: Stopping Scroll Chaining

Learn overscroll-behavior to stop scroll chaining out of panels and modals, control pull-to-refresh and swipe-back gestures, and set values per axis.

You have probably felt this. You scroll a chat panel or a dropdown list down to its last item, keep flicking, and suddenly the whole page behind it starts moving. It feels like the page grabbed the scroll away from you. This handoff is called scroll chaining, and it is the browser's default behavior.

The overscroll-behavior property lets you decide what happens when a scroll container reaches the end of its content. You can stop the handoff, remove the bounce or glow effect, and even disable gestures such as pull-to-refresh and swipe-back. It takes only one line, but it makes panels, modals, drawers and carousels feel solid.

What is scroll chaining?

When you scroll with a wheel, trackpad or finger, the browser sends the movement to the innermost scroll container under the pointer. If that container is already at its limit in that direction, the leftover motion, called overscroll, passes to the next scroll container outward, and finally to the page itself.

flowchart TD
  A["Wheel or touch scroll on a panel"] --> B{"Panel has room to scroll?"}
  B -->|"yes"| C["Panel scrolls"]
  B -->|"no, at the end"| D{"overscroll-behavior"}
  D -->|"auto (default)"| E["Page behind scrolls (chaining)"]
  D -->|"contain"| F["Nothing moves, panel keeps the scroll"]
  D -->|"none"| G["Nothing moves and no bounce or glow"]

A scroll that hits the end of a panel is passed outward unless overscroll-behavior says otherwise.

Chaining is helpful for ordinary content, because a short code block inside an article should not trap your scroll. It becomes annoying for self-contained UI: menus, chat logs, modals, autocomplete lists, sidebars and embedded maps.

The values

Value Chains to the parent? Local effects (bounce, glow) Navigation gestures
auto Yes (the default) Yes Allowed
contain No Yes Allowed in most browsers for the container
none No No Disabled

contain is the one you will use most. It stops the handoff but leaves the box's own overscroll effect, such as the rubber band on macOS and iOS or the glow on Android, so the user still gets feedback that they reached the end. none also removes that effect.

The property applies to scroll containers, meaning elements with overflow: auto, scroll or overlay whose content really overflows, and to the page itself when set on html. Setting it on a box that doesn't scroll does nothing.

The behavior only affects scrolling that the user starts. Calls such as element.scrollTo() and scrollIntoView() are not blocked.

Try it: stop the page from moving

The page in this demo is deliberately tall, and a counter shows how far the page has scrolled. Scroll inside each panel past its end and watch the counter. The left panel chains; the right one does not.

Chaining versus contain

Scroll the left panel to its last line and keep going: the counter starts to rise because the page takes over. Do the same on the green panel and the counter stays put. In many browsers, a single uninterrupted scroll gesture stays attached to the container it started in, so to see the difference clearly, pause after reaching the end and then scroll again.

Per-axis control

Scroll chaining can happen horizontally and vertically, and sometimes you want different rules for each. There are two longhands, overscroll-behavior-x and overscroll-behavior-y, and the shorthand takes one or two values (x first, then y):

CSS
.carousel { overscroll-behavior-x: contain; }       /* only the x axis */
.sheet    { overscroll-behavior: none contain; }    /* x: none, y: contain */
.modal    { overscroll-behavior: contain; }         /* both axes */

A horizontal scroller is a classic case. On many desktop browsers a two-finger horizontal swipe past the edge of a carousel triggers history navigation, and the user lands on the previous page by accident. overscroll-behavior-x: contain on the carousel keeps the gesture inside it. The contain value on the container is enough to stop the chaining, while the page itself keeps its normal behavior.

Where it earns its keep

Modals, drawers and dropdowns

A modal dialog is a scroll container with a page underneath. If the user scrolls the modal's content to the end, chaining moves the page behind it, which is disorienting. Add overscroll-behavior: contain to the scrollable part of the modal.

That covers scrolling inside the modal. Wheel movement over the backdrop still goes to the page, because the backdrop is not a scroll container. For a complete "scroll lock", also stop the page itself from scrolling while a dialog is open. With :has(), no JavaScript is needed:

CSS
html:has(dialog[open]) {
  overflow: hidden;
  scrollbar-gutter: stable;   /* keeps the layout from jumping sideways */
}
A modal that locks the page

Open the dialog, scroll its terms to the end and keep scrolling, then turn the lock option off and try the backdrop. With the lock on, nothing behind the dialog moves. With it off, wheel movement over the dim backdrop scrolls the page, even though the dialog itself no longer chains.

Pull-to-refresh and edge bounce

Some mobile browsers refresh the page when you drag down from the very top, and many show a bounce or glow at the page edges. That is welcome on a news article, and a real problem in a web app that draws on a canvas, implements its own swipe-to-refresh, or has a full-screen map. Set the property on the root:

CSS
html, body { overscroll-behavior-y: contain; }   /* no browser pull-to-refresh */

none additionally removes the bounce effect in browsers that support it. Use this sparingly: pull-to-refresh is a gesture people know, so remove it only if your interface provides a better replacement.

Nested code blocks and chat logs

A <pre> with horizontal scrolling inside a long article, a dropdown list of cities, and a chat log are all small scroll areas inside a bigger page. Give each overscroll-behavior: contain so a flick past the end does nothing to the page, then pair it with the habits from Overflow: max-height, scrollbar-gutter and keyboard focus.

Things to remember

  • The property takes effect on the box that scrolls, not on its parents or children.
  • It changes user-driven scrolling only. Scripted scrolling is unaffected, and so is the panel's own scrolling.
  • Older Safari versions ignore it: before Safari 16, overscroll-behavior did nothing on iOS, so don't rely on it as your only scroll lock there.
  • Don't use none on the whole page just to hide a bounce effect. It also removes gestures some people depend on.
  • Position tricks like sticky headers and scroll snapping (see Scroll Snap) combine well with contain on the scroller.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is scroll chaining?

    When an inner scroll container can't scroll any further, the browser hands the remaining motion to the next scroll container outward. That handoff is scroll chaining.
  2. 2. Which value stops chaining but keeps the box's own bounce or glow effect?

    contain blocks the handoff but still lets the container show its own overscroll effect. none removes that effect too.
  3. 3. How do you stop only horizontal overscroll, for example to avoid swipe-back navigation from a carousel?

    overscroll-behavior-x controls the horizontal axis only. overflow-x: hidden would stop the carousel from scrolling at all.
  4. 4. A modal's content has overscroll-behavior: contain, yet the page still scrolls when you wheel over the dark backdrop. Why?

    overscroll-behavior guards the container it is set on. To stop the page scrolling while a dialog is open, also set overflow: hidden on the root, for example with html:has(dialog[open]).
  5. 5. Does overscroll-behavior: contain prevent element.scrollTo() from moving the page?

    The property deals with the handoff of user scrolling. Scripts can still scroll any container or the page.

Summary

  • Scroll chaining passes leftover scroll to the parent or the page when a scroll container hits its end.
  • overscroll-behavior has three values: auto (chains), contain (stops chaining, keeps local effects) and none (stops both).
  • Use -x and -y longhands, or two shorthand values, to set each axis separately.
  • Put contain on modals, drawers, dropdowns, chat logs and horizontal carousels. Add overflow: hidden on the root if the whole page must stay put.
  • Setting overscroll-behavior-y: contain on html disables browser pull-to-refresh, so do it only when your app handles that gesture itself.

Next: Flexbox.