🌀 CSS overscroll-behavior-block — Complete Tutorial

🌐 What Is overscroll-behavior-block?

The overscroll-behavior-block property controls what happens when a user scrolls **past the boundary of a scrollable container** along theblock axis.

The block axis depends on the document’s writing-mode:

  • ➡ Horizontal writing (English): block = vertical scroll (top ↕ bottom)
  • ⬆ Vertical writing (Japanese/Chinese): block = horizontal scroll (left ↔ right)
>>“Use overscroll-behavior-block when you want to control vertical scroll chaining or overscroll effects — especially inside modals, panels, and nested scroll areas.”

Note

✔ Logical version of overscroll-behavior-y
✔ Prevents scroll chaining along block direction
✔ Essential for modals, sidebars, chat apps, and vertical content layouts

📦 Syntax

Syntax

overscroll-behavior-block: auto | contain | none;
ValueDescription
autoDefault. Allows scroll chaining + browser overscroll effects.
containPrevents scroll chaining along block direction but keeps bounce/glow effects.
nonePrevents scroll chaining AND disables browser overscroll effects (e.g., pull-to-refresh).

📌 1. Prevent Page From Scrolling When a Panel Reaches the Top/Bottom

Scrollable panel

.panel {
  overflow-y: auto;
  overscroll-behavior-block: contain;
}

When the user scrolls to the top or bottom of the panel, the page behind it will NOT scroll.

📌 2. Disable Vertical Overscroll Completely

Disable bounce/pull-to-refresh

body {
  overscroll-behavior-block: none;
}

Prevents bouncing, glow effects, and pull-to-refresh gestures. Common in fullscreen web apps.

📌 3. Vertical Scroll Lock Inside Modals

Modal content

.modal-content {
  overflow-y: auto;
  overscroll-behavior-block: contain;
}

📌 4. Vertical Writing Mode Example (Block Axis Becomes Horizontal)

Vertical writing overscroll

.vertical-section {
  writing-mode: vertical-rl;
  overflow-x: auto; /* block axis = inline-left/right? no — block axis flips */
  overscroll-behavior-block: contain;
}

In vertical writing, **block-axis scrolling is horizontal**. This property will now control horizontal overscroll!

📌 5. Prevent Scroll Leaking in Nested Chat Interfaces

Chat message list

.chat-list {
  overflow-y: auto;
  overscroll-behavior-block: contain;
}

Prevents the page from scrolling when reaching top/bottom of chat messages.

📌 6. Mobile Browsers — Stop Pull-To-Refresh

No pull-to-refresh

html, body {
  overscroll-behavior-block: none;
}

Essential for PWAs (Progressive Web Apps) and full-height web apps.

🧪 Real-World Use Cases

1️⃣ Scrollable Sidebar

Sidebar

.sidebar {
  overflow-y: auto;
  overscroll-behavior-block: contain;
}

2️⃣ Long Forms in a Dialog

Long form

.form-wrapper {
  overflow-y: scroll;
  overscroll-behavior-block: contain;
}

3️⃣ Sticky Headers Without Scroll Chaining Issues

Sticky header

header {
  position: sticky;
  top: 0;
  overscroll-behavior-block: none;
}

⚠️ Common Mistakes

  • ❌ Applying it on non-scrollable elements
  • ❌ Assuming it stops horizontal scroll (use inline version)
  • ❌ Using contain expecting bounce or pull-to-refresh to disappear (use none)
  • ❌ Forgetting that block axis changes in vertical writing modes

Note

Use overscroll-behavior-block to control vertical (or block-axis) scrolling, especially for nested layouts and smooth UI experiences.

🔥 Summary

The overscroll-behavior-block property controls block-axis overscroll behavior, preventing scroll chaining and optionally disabling browser overscroll effects. It's the logical, writing-mode-aware version of overscroll-behavior-y.

>>“For stable, app-like scrolling in modals, chat windows, and nested containers — use overscroll-behavior-block.”

Learn more →MDN Docs 📘