CSS overscroll-behavior-y Property

CSS overscroll-behavior-y Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The overscroll-behavior-y property controls how the user-agent should behave when a scrolling action on an element reaches the vertical scroll boundary (top or bottom). In practice this means it determines whether a vertical scroll that would “overshoot” an element’s scroll range is allowed to produce effects outside that element - for example, chaining the scroll to a parent container, triggering the browser’s pull-to-refresh, or showing the native bounce/rubber-band overscroll. It is strictly axis-specific, so it only governs vertical gestures and flings while leaving horizontal behavior unaffected.

This property is commonly used to contain scroll interactions in nested or embedded scrollable regions so that an inner scroll area does not unintentionally move outer content. For example, in a modal with a scrollable body or a vertically swiped carousel you can prevent the page behind it from moving when the inner content hits its top or bottom. It pairs conceptually with the X-axis counterpart overscroll-behavior-x and with the shorthand overscroll-behavior, which let you control overscroll behavior by axis or all at once.

In practice you’ll often combine vertical overscroll control with overflow management and pointer/touch handling: for example, ensuring an element has the appropriate scroll container behavior via overflow and adjusting gesture handling with touch-action so touch gestures are interpreted as intended. Setting overscroll-behavior-y on the actual scroll container (the element that receives the scroll) is important - applying it to a non-scrolling ancestor won’t contain the overscroll for that scroller.

Conceptually, this property affects user-initiated scrolls and the transfer of momentum or chain reactions between nested scrolling contexts: it prevents propagation of the scroll action beyond the element boundary, and it suppresses certain platform-specific overscroll affordances like pull-to-refresh or bounce effects. It doesn’t change layout or how much content fits in the box; it only changes what happens when the user tries to scroll past the element’s vertical limits.

Definition

Initial value: auto
Applies to: non-replaced block-level elements and non-replaced inline-block elements
Inherited: no
Computed value: as specified
Animatable: yes
JavaScript syntax: object.style.overscrollBehaviorY

Syntax

overscroll-behavior-y: auto | contain | none

Values

autoThe default scroll overflow behavior occurs as normal.
containDefault scroll overflow behavior is observed inside the element this value is set on (e.g. "bounce" effects or refreshes), but no scroll chaining occurs to neighboring scrolling areas, e.g. underlying elements will not scroll.
noneNo scroll chaining occurs to neighboring scrolling areas, and default scroll overflow behavior is prevented.

Example

HTML

<div class="main-content">

  <h1>Scroll Down to the Box</h1>

  <p>Keep scrolling... the main page is very long.</p>

  

  <div class="scroll-container">

    <div class="content-inside">

      <h3>Internal Scroll Box</h3>

      <p>Try scrolling to the very bottom of THIS box.</p>

      <p>Content...</p>

      <p>Content...</p>

      <p>Content...</p>

      <p>Content...</p>

      <p>You have reached the end. Notice the main page doesn't move!</p>

    </div>

  </div>



  <p>More main page content below...</p>

  <div class="spacer"></div>

</div>

CSS

/* The parent container with the scrollbar */
.scroll-container {
  width: 300px;
  height: 200px;
  overflow-y: auto;
  border: 2px solid #333;
  background-color: #f4f4f4;
  
  /* PREVENTS SCROLL CHAINING */
  overscroll-behavior-y: contain;
}

/* Just styling for the example */
.content-inside {
  padding: 15px;
  height: 500px; /* Making it taller than the container to force a scroll */
  background: linear-gradient(to bottom, #fff, #ddd);
}

.main-content {
  font-family: sans-serif;
  padding: 20px;
}

.spacer {
  height: 1000px; /* Adds length to the main page to test chaining */
  background: #eee;
  margin-top: 20px;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS overscroll-behavior-y property. Hover over a browser icon to see the version that first introduced support for this CSS property.