// config/scroll-boundary.ts
export type OverscrollMode = 'auto' | 'contain' | 'none';

export interface ScrollBoundaryConfig {
  mode: OverscrollMode;
  restrictX?: boolean;
  restrictY?: boolean;
  preservePullToRefresh?: boolean;
}

export const DEFAULT_SCROLL_CONFIG: ScrollBoundaryConfig = {
  mode: 'contain',
  restrictX: false,
  restrictY: true,
  preservePullToRefresh: false,
};

/* styles/scroll-boundary.css */
:root {
  --scroll-boundary-mode: contain;
  --scroll-boundary-x: auto;
  --scroll-boundary-y: auto;
}

/* Base scroll container with boundary isolation */
.scroll-context-isolated {
  overflow: auto;
  overscroll-behavior: var(--scroll-boundary-mode);
  
  /* Directional overrides when specific axis isolation is required */
  overscroll-behavior-x: var(--scroll-boundary-x);
  overscroll-behavior-y: var(--scroll-boundary-y);
  
  /* Prevent touch-action conflicts on mobile */
  touch-action: pan-y pan-x;
}

/* Utility: Lock vertical chaining only */
.scroll-context-isolated--y-only {
  --scroll-boundary-x: auto;
  --scroll-boundary-y: contain;
}

/* Utility: Lock horizontal chaining only */
.scroll-context-isolated--x-only {
  --scroll-boundary-x: contain;
  --scroll-boundary-y: auto;
}

/* Global pull-to-refresh suppression (use sparingly) */
body[data-pull-refresh="disabled"] {
  overscroll-behavior-y: none;
}

le manipulation and respects SSR hydration.

// components/OverlayViewport.tsx
import { useEffect, useRef } from 'react';
import type { ScrollBoundaryConfig } from '../config/scroll-boundary';
import { DEFAULT_SCROLL_CONFIG } from '../config/scroll-boundary';

interface OverlayViewportProps {
  isOpen: boolean;
  config?: Partial<ScrollBoundaryConfig>;
  children: React.ReactNode;
}

export function OverlayViewport({ isOpen, config = {}, children }: OverlayViewportProps) {
  const viewportRef = useRef<HTMLDivElement>(null);
  const mergedConfig = { ...DEFAULT_SCROLL_CONFIG, ...config };

  useEffect(() => {
    const el = viewportRef.current;
    if (!el) return;

    // Apply CSS variables for dynamic configuration without inline style bloat
    el.style.setProperty('--scroll-boundary-mode', mergedConfig.mode);
    el.style.setProperty('--scroll-boundary-x', mergedConfig.restrictX ? 'contain' : 'auto');
    el.style.setProperty('--scroll-boundary-y', mergedConfig.restrictY ? 'contain' : 'auto');
  }, [mergedConfig]);

  return (
    <div
      ref={viewportRef}
      className={`scroll-context-isolated ${isOpen ? 'is-active' : ''}`}
      aria-hidden={!isOpen}
    >
      {children}
    </div>
  );
}

Architecture Rationale

• CSS Variables over Inline Styles: Using custom properties keeps the DOM clean, enables theme switching, and avoids React/Vue reconciliation overhead from frequent style object changes.
• Directional Separation: Splitting x and y constraints prevents accidental cross-axis locking, which is a common source of mobile navigation bugs.
• touch-action Synergy: Explicitly defining touch-action ensures the browser's gesture recognizer doesn't conflict with overscroll isolation, particularly on iOS Safari where pan gestures can override CSS boundaries if not declared.
• SSR Compatibility: The component applies configuration via useEffect, preventing hydration mismatches and ensuring the initial render matches the server markup.

Pitfall Guide

1. Applying to the Backdrop Instead of the Scroll Container

Explanation: Developers frequently attach the property to the modal backdrop or overlay wrapper. Since the backdrop typically has overflow: visible or no scrollable content, the browser ignores the declaration. Scroll chaining continues when the user interacts with the actual content panel. Fix: Inspect the DOM tree and locate the element with overflow: auto/scroll and a constrained height. Apply the property directly to that node. Use browser devtools to verify the computed overscroll-behavior value on the scroll container.

2. Ignoring Directional Variants in Mixed-Axis Layouts

Explanation: Using the shorthand overscroll-behavior: contain locks both axes. In horizontal carousels or swipeable galleries, this prevents vertical page scrolling entirely, trapping the user. Fix: Use overscroll-behavior-x: contain and overscroll-behavior-y: auto for horizontal-only containers. Conversely, use overscroll-behavior-y: contain for vertical drawers while preserving horizontal page scroll.

3. Confusing overscroll-behavior with overflow

Explanation: The property does not create scrollable regions. It only controls momentum propagation when a boundary is reached. Applying it to a non-scrolling element has zero effect. Fix: Ensure the target element has explicit height/width constraints and overflow: auto or overflow: scroll. Use max-height with overflow: auto for flexible panels that only scroll when content exceeds the threshold.

4. Overusing none and Breaking Platform Expectations

Explanation: Setting overscroll-behavior: none removes native edge feedback. On iOS, this disables rubber-banding; on Android, it removes the overscroll glow. Users may perceive the interface as unresponsive or broken. Fix: Reserve none for immersive applications, canvas editors, or custom scroll implementations. For standard UI overlays, prefer contain to maintain platform familiarity while still isolating scroll momentum.

5. Flex/Grid Containers Without Explicit Height Constraints

Explanation: When a flex or grid child lacks a defined height, it expands to fit its content. The browser never reaches a scroll boundary, so overscroll-behavior never triggers. Fix: Apply height: 100%, max-height: 80vh, or flex: 1 1 auto with a parent constraint. Verify that the container actually generates a scrollbar before debugging isolation behavior.

6. Framework Re-Render Cycles Stripping Inline Styles

Explanation: In React, Vue, or Svelte, frequent state updates can cause inline style objects to be recreated, triggering unnecessary style recalculations. Some optimization plugins may also strip unknown CSS properties during build. Fix: Use CSS classes or custom properties instead of inline style objects. Verify that your build pipeline (Vite, Webpack, PostCSS) does not purge overscroll-behavior during CSS minification. Add it to safelist configurations if necessary.

7. Neglecting scroll-snap and overscroll-behavior Conflicts

Explanation: When scroll-snap-type is active, the browser may override overscroll isolation to enforce snap alignment. This can cause unexpected momentum transfer to parent contexts during snap transitions. Fix: Test snap containers with overscroll-behavior: contain in isolation. If chaining persists during snap, apply overscroll-behavior: none to the snap container and implement custom boundary logic if strict isolation is required.

Production Bundle

Action Checklist

• Identify all nested scroll containers in the application (modals, drawers, virtualized lists, carousels)
• Verify each container has explicit height/width constraints and overflow: auto/scroll
• Apply overscroll-behavior: contain to vertical-only containers and directional variants to mixed-axis layouts
• Test on iOS Safari and Android Chrome to confirm native overscroll feedback is preserved or suppressed as intended
• Remove legacy JavaScript scroll-locking event listeners and overflow: hidden body toggles
• Validate Core Web Vitals metrics, specifically CLS and Input Latency, before and after migration
• Add overscroll-behavior to CSS purge safelist if using utility-first frameworks (Tailwind, UnoCSS)
• Document the isolation strategy in the component library guidelines to prevent regression

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Modal/Drawer with vertical content	overscroll-behavior-y: contain	Isolates vertical scroll while preserving horizontal page navigation	Zero runtime cost, reduces JS bundle
Horizontal image gallery/carousel	overscroll-behavior-x: contain + overscroll-behavior-y: auto	Prevents horizontal chaining but allows vertical page scroll	Minimal CSS overhead, improves mobile UX
Full-screen immersive app/canvas	overscroll-behavior: none on root container	Suppresses all native overscroll feedback for custom physics	Requires custom scroll implementation, higher dev cost
Mobile PWA with pull-to-refresh	overscroll-behavior-y: none on body + contain on overlays	Disables global pull-to-refresh while isolating nested contexts	Improves app-like feel, may confuse users expecting native refresh
Virtualized list with infinite scroll	overscroll-behavior: contain on viewport	Prevents background scroll during momentum deceleration	Zero cost, critical for performance on low-end devices

Configuration Template

/* scroll-boundary.config.css */
:root {
  /* Global defaults */
  --scroll-boundary-mode: contain;
  --scroll-boundary-x: auto;
  --scroll-boundary-y: auto;
  
  /* Platform-specific overrides */
  --scroll-boundary-ios: contain;
  --scroll-boundary-android: contain;
}

/* Base isolation class */
.isolated-scroll-context {
  overflow: auto;
  overscroll-behavior: var(--scroll-boundary-mode);
  overscroll-behavior-x: var(--scroll-boundary-x);
  overscroll-behavior-y: var(--scroll-boundary-y);
  touch-action: pan-y pan-x;
}

/* Directional utilities */
.isolated-scroll-context--vertical {
  --scroll-boundary-x: auto;
  --scroll-boundary-y: var(--scroll-boundary-mode);
}

.isolated-scroll-context--horizontal {
  --scroll-boundary-x: var(--scroll-boundary-mode);
  --scroll-boundary-y: auto;
}

/* Global pull-to-refresh control */
body[data-native-refresh="false"] {
  overscroll-behavior-y: none;
}

/* Framework integration hook */
[data-scroll-boundary="active"] {
  --scroll-boundary-mode: contain;
}

Quick Start Guide

1. Locate the scroll container: Open your browser's developer tools, inspect the modal/drawer/carousel, and identify the element that generates the scrollbar. It must have overflow: auto or overflow: scroll and a constrained dimension.
2. Apply the isolation property: Add overscroll-behavior: contain to the identified element. If the container scrolls horizontally, use overscroll-behavior-x: contain instead.
3. Test boundary behavior: Scroll to the top or bottom of the container. Verify that momentum stops at the edge and does not propagate to the background page. Check iOS and Android devices to confirm overscroll feedback matches your intent.
4. Remove legacy workarounds: Delete any JavaScript event listeners that call preventDefault() on scroll/wheel/touch events. Remove overflow: hidden toggles on the <body> element. Verify that layout shift metrics improve in your performance dashboard.
5. Integrate into your component library: Add the isolation class to your design system's overlay components. Document the directional variants and platform considerations to prevent future regression.