CSS overscroll-behavior-y Property

What You’ll Learn

The overscroll-behavior-y property controls what happens when a scrollable element reaches its vertical edge. It is essential for modals, chat panels, feed lists, and any nested area that scrolls up and down inside a larger page.

Introduction

The overscroll-behavior-y property in CSS is used to control the behavior of a scrolling container when the scroll position reaches the edge of the content along the vertical axis.

This property is particularly useful for preventing the default “bounce” or “pull-to-refresh” behavior on touch devices or when working with nested scrollable elements. By setting this property, developers can enhance the user experience by providing a more controlled and consistent scrolling behavior.

By customizing the overscroll behavior, developers can prevent unexpected scrolling actions, such as scrolling the entire page when reaching the end of a nested scrollable element.

Definition and Usage

Use overscroll-behavior-y on elements that scroll vertically inside a larger page, such as modal bodies, chat panels, off-canvas drawers, and nested feed lists.

Pair it with overflow-y: auto or overflow: auto so the element actually scrolls on the vertical axis. Then set overscroll-behavior-y: contain to keep vertical edge scrolling inside that box.

The overscroll-behavior shorthand sets both physical axes at once. In horizontal writing modes, overscroll-behavior-block is the logical equivalent of the vertical axis. Use overscroll-behavior-x when you need to control horizontal overscroll separately.

📝 Syntax

The syntax for the overscroll-behavior-y property is straightforward and can be applied to any scrollable container.

element {
  overscroll-behavior-y: value;
}

It can be applied to any scrollable element. Here, value can be one of the predefined keywords described below.

Basic Example

.scroll-container {
  width: 300px;
  height: 200px;
  overflow: auto;
  overscroll-behavior-y: contain;
}
.content {
  height: 400px;
  background: linear-gradient(#e66465, #9198e5);
}

Syntax Rules

• Accepted values: auto, contain, and none.
• The element must be scrollable on the vertical axis, usually with overflow-y: auto or overflow: auto.
• overscroll-behavior is a shorthand for overscroll-behavior-x and overscroll-behavior-y.
• In horizontal writing mode, overscroll-behavior-block maps to the same axis as overscroll-behavior-y.
• contain is the most common choice for modal bodies, chat panels, and nested vertical scroll lists.

🎯 Default Value

The default value of the overscroll-behavior-y property is auto. This means the default scroll behavior of the browser will occur when the scroll reaches the edge of the content.

With auto, scrolling past the top or bottom edge of a nested scroll area may chain to the page behind it or trigger platform-specific bounce effects.

💎 Property Values

Examples Gallery

Prevent vertical scroll overflow with contain, compare default auto behavior, disable vertical bounce and pull-to-refresh with none, and isolate scroll inside a modal or chat body.

<style>
  .scroll-container {
    width: 300px;
    height: 200px;
    overflow: auto;
    border: 1px solid #ccc;
    overscroll-behavior-y: contain;
  }
  .content {
    height: 400px;
    background: linear-gradient(#e66465, #9198e5);
  }
</style>

<div class="scroll-container">
  <div class="content"></div>
</div>

.panel {
  width: 300px;
  height: 160px;
  overflow: auto;
  overscroll-behavior-y: auto;
  border: 1px solid #cbd5e1;
  border-radius: 0.5rem;
}

.feed {
  width: 320px;
  height: 180px;
  overflow: auto;
  overscroll-behavior-y: none;
  border: 1px solid #334155;
  border-radius: 0.75rem;
}

.modal-body {
  max-height: 240px;
  overflow: auto;
  overscroll-behavior-y: contain;
  border: 1px solid #cbd5e1;
  border-radius: 0.5rem;
}

overscroll-behavior vs block vs x

The overscroll-behavior shorthand sets both physical axes at once. overscroll-behavior-y targets only the vertical axis (top and bottom), and overscroll-behavior-x targets only the horizontal axis (left and right). In horizontal writing modes, overscroll-behavior-block is the logical equivalent of the vertical axis.

/* Shorthand — both physical axes */
.modal-body {
  overscroll-behavior: contain;
}

/* Vertical axis only */
.chat-panel {
  overscroll-behavior-x: auto;
  overscroll-behavior-y: contain;
}

♿ Accessibility

• Do not trap users — Preventing vertical scroll chaining is helpful in modals and chat panels, but ensure keyboard users can still scroll nested regions with arrow keys or focus management.
• Keep scrollable regions discoverable — Pair overscroll control with visible scroll cues and sufficient contrast on vertically scrollable content.
• Prefer contain on modal bodies — so background page movement does not disorient screen reader users when scrolling nested panels.
• Test touch devices — Vertical overscroll behavior is especially noticeable on swipe gestures in modals, drawers, and chat interfaces.

💡 Best Practices