AddThisFeature

Scroll Containment Utility

Stop the page scrolling behind an overlay without shifting the layout underneath.

moderate Components & Primitives

What it adds

A shared utility that locks background scrolling while an overlay is open and releases it cleanly when the overlay closes.

What your agent is told to do

5
  1. 1

    Find every surface that currently locks or unlocks page scrolling on its own — modals, drawers, menus, mobile navigation, image viewers — and route all of them through one utility instead of each toggling styles directly.

  2. 2

    Reserve the width the scrollbar occupied when scrolling is locked, so the page behind does not widen by the scrollbar's width and visibly shift at the moment the overlay appears.

  3. 3

    Keep a count of active locks rather than a boolean. Closing one of two stacked overlays must not release the lock while the other is still open.

  4. 4

    Record the exact styles and scroll offset in place before locking, and restore precisely those values on release rather than resetting to a hardcoded default.

  5. 5

    Do not lock scrolling by fixing the document to the viewport as a first resort. On touch devices it discards the scroll position and snaps the user back to the top when the overlay closes; if you use that approach, capture and restore the offset explicitly.

Edge cases it handles

7
  • Locking scroll usually removes the scrollbar, and the page reflows into the reclaimed width. Compensate for that width on the document and on any fixed-position elements, or the whole layout jumps sideways each time an overlay opens.
  • Touch scrolling on iOS ignores an overflow lock on the document and continues to scroll the page behind the overlay. Handle that platform explicitly rather than assuming an overflow rule is enough.
  • Two or more overlays can be open at once — a dialog that opens a confirmation, a drawer containing a menu. Reference-count the locks so the last one to close is the one that releases.
  • The utility must restore the original inline styles, overflow values, and scroll offset it found, not the values it assumed were there. Another feature may have set them first.
  • A scroll container inside the overlay must remain scrollable while the background is locked, and reaching its end must not chain the scroll onto the page behind it.
  • An overlay that unmounts abruptly — a route change, an error boundary, a hot reload in development — must still release the lock, or the app is left permanently unscrollable.
  • Users who never see a scrollbar, because the pointer is a touchscreen or the platform overlays its scrollbars, must gain no compensating padding at all.

Definition of done

8
  • Every overlay in the app locks background scrolling through the same shared utility.
  • Opening and closing an overlay causes no horizontal shift in the page behind it.
  • Background scrolling is genuinely prevented on touch devices, not only with a mouse.
  • Nested and simultaneous overlays release the lock only when the last one closes.
  • Scroll position and the original styles are exactly as they were before the overlay opened.
  • Scrollable regions inside an overlay still scroll, and do not chain to the page beneath.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.