CSS overscroll-behavior-block Property

Description

The overscroll-behavior-block property controls how the user agent should behave when a scrollable box reaches the end of its scrollable range along the block axis (the axis that follows lines of text in the current writing mode). It determines whether the default platform behaviors that normally occur at that boundary — such as visual overscroll effects, browser-initiated navigation gestures, or the continuation of scrolling into an ancestor — are allowed to run or should be suppressed. Because it targets the block axis, its effect depends on the element’s writing mode: in common horizontal writing modes this corresponds to the vertical axis, while in vertical-rl/writing-mode scenarios it corresponds to the horizontal axis.

Practically, this property is used to control scroll chaining and the user experience around "edge" interactions. When an inner scroller reaches its block-edge, the browser typically either bounces/paints an overscroll affordance, continues the scroll into the parent (scroll chaining), or triggers a platform gesture (for example, a pull-to-refresh or a navigation swipe). By configuring overscroll-behavior-block, authors can choose whether those effects should be permitted to propagate beyond the element’s block-edge or be contained locally, which is especially useful for UI components like side panels, modals, or custom scrollers where you want to prevent accidental page-level gestures.

In nested scrolling scenarios, this property is a key tool to make scrolling predictable. For example, when a nested content area is intended to consume all scroll input until it is fully exhausted (so the viewport doesn’t suddenly start moving or a browser gesture isn’t triggered), the block-axis behavior can be set to suppress propagation. Conversely, if you want an inner scroller to yield to its ancestor once it reaches its end, the property can be configured to allow that chain. It influences input from touch, trackpad, and wheel devices by affecting whether scroll input is captured or allowed to bubble up to ancestor scrolling contexts and to the browser itself.

For composition and implementation, it is commonly combined with related scrolling and input properties to achieve the desired interaction model: the shorthand overscroll-behavior can set behavior on both axes at once, and the axis-specific overscroll-behavior-x controls the inline axis counterpart. When fine-tuning gesture recognition and scroll handling you may also consider touch-action (which affects how pointer/touch gestures are interpreted) and scroll-behavior (which governs animated scrolling), using them together to create smooth, consistent, and accessible scrolling experiences.

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.overscrollBehaviorBlock

Syntax

overscroll-behavior-block: 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="page">

    <h1>overscroll-behavior-block demo</h1>

    <p class="note">Scroll inside each box to the top or bottom. Compare how the page reacts when you reach the edges.</p>



    <div class="row">

        <section class="box default">

            <h2>Default (auto)</h2>

            <div class="scroller">

                <ol>

                    <li>Item 1</li>

                    <li>Item 2</li>

                    <li>Item 3</li>

                    <li>Item 4</li>

                    <li>Item 5</li>

                    <li>Item 6</li>

                    <li>Item 7</li>

                    <li>Item 8</li>

                    <li>Item 9</li>

                    <li>Item 10</li>

                    <li>Item 11</li>

                    <li>Item 12</li>

                    <li>Item 13</li>

                    <li>Item 14</li>

                    <li>Item 15</li>

                    <li>Item 16</li>

                    <li>Item 17</li>

                    <li>Item 18</li>

                    <li>Item 19</li>

                    <li>Item 20</li>

                </ol>

            </div>

        </section>



        <section class="box contain">

            <h2>contain</h2>

            <div class="scroller">

                <ol>

                    <li>Item 1</li>

                    <li>Item 2</li>

                    <li>Item 3</li>

                    <li>Item 4</li>

                    <li>Item 5</li>

                    <li>Item 6</li>

                    <li>Item 7</li>

                    <li>Item 8</li>

                    <li>Item 9</li>

                    <li>Item 10</li>

                    <li>Item 11</li>

                    <li>Item 12</li>

                    <li>Item 13</li>

                    <li>Item 14</li>

                    <li>Item 15</li>

                    <li>Item 16</li>

                    <li>Item 17</li>

                    <li>Item 18</li>

                    <li>Item 19</li>

                    <li>Item 20</li>

                </ol>

            </div>

        </section>



        <section class="box none">

            <h2>none</h2>

            <div class="scroller">

                <ol>

                    <li>Item 1</li>

                    <li>Item 2</li>

                    <li>Item 3</li>

                    <li>Item 4</li>

                    <li>Item 5</li>

                    <li>Item 6</li>

                    <li>Item 7</li>

                    <li>Item 8</li>

                    <li>Item 9</li>

                    <li>Item 10</li>

                    <li>Item 11</li>

                    <li>Item 12</li>

                    <li>Item 13</li>

                    <li>Item 14</li>

                    <li>Item 15</li>

                    <li>Item 16</li>

                    <li>Item 17</li>

                    <li>Item 18</li>

                    <li>Item 19</li>

                    <li>Item 20</li>

                </ol>

            </div>

        </section>

    </div>

</div>

CSS

/* Basic page layout */
* {
    box-sizing: border-box;
}

html, body {
    height: 100%;
    margin: 0;
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial;
    background: linear-gradient(180deg, #eef2f5 0%, #ffffff 100%);
    color: #111827;
}

.page {
    max-width: 1100px;
    margin: 28px auto;
    padding: 20px;
}

h1 {
    margin: 0 0 8px 0;
    font-size: 20px;
}

.note {
    margin: 0 0 16px 0;
    color: #555;
    font-size: 13px;
}

/* Row of boxes */
.row {
    display: flex;
    gap: 16px;
}

.box {
    flex: 1 1 0;
    display: flex;
    flex-direction: column;
    height: 60vh;
    border: 1px solid #d1d5db;
    border-radius: 8px;
    overflow: hidden;
    background: #fff;
}

.box h2 {
    margin: 12px 12px 0 12px;
    font-size: 14px;
}

.scroller {
    margin: 12px;
    padding: 8px 12px;
    background: #fbfdff;
    border-radius: 6px;
    overflow-y: auto;
    scroll-behavior: smooth;
    /* Tall content will make this element vertically scrollable */
}

.scroller ol {
    margin: 0;
    padding-left: 18px;
}

.scroller li {
    padding: 8px 6px;
    border-bottom: 1px solid rgba(0,0,0,0.04);
    font-size: 14px;
}

/* Demonstrate overscroll-behavior-block */
.default .scroller {
    /* browser default behavior: overscroll is allowed to propagate to parent/page */
    overscroll-behavior-block: auto;
}

.contain .scroller {
    /* contain vertical overscroll inside the scroller (prevent page from scrolling when reaching edges) */
    overscroll-behavior-block: contain;
}

.none .scroller {
    /* block any scroll chaining and also prevent default actions like pull-to-refresh */
    overscroll-behavior-block: none;
}

/* Small responsive adjustment */
@media (max-width: 800px) {
    .row {
        flex-direction: column;
    }
}

Result

Editor

Browser Support

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