Hold the page. Let it go cleanly.

Scroll Lock
The page stays put while your modal is open.

Mark a dialog with data-scroll-lock, or call lockScroll(), and the page behind it stops scrolling without jumping sideways, even on iPhone.
Install it, try the live preview, then read the full reference.

npm install @samline/scroll-lock

About 3.8 KB gzipZero dependenciesMIT licensed

Scroll Lock previewLive preview
Scrollbar gap
Pin body

Page scrolls

The page behind is locked

Line 1: this list still scrolls.

Line 2: this list still scrolls.

Line 3: this list still scrolls.

Line 4: this list still scrolls.

Line 5: this list still scrolls.

Line 6: this list still scrolls.

Line 7: this list still scrolls.

Line 8: this list still scrolls.

Line 9: this list still scrolls.

Line 10: this list still scrolls.

Two locks held

Close this one and the page stays locked until the first closes too.

ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than overflow: hidden

One line of CSS,
and everything it misses.

Locks that nest

A drawer opens a dialog that opens a menu: each holds its own lock, and the page unlocks after the last one, in any order.

No sideways jump

The scrollbar width moves to the body padding and to --scroll-lock-gap, so content and fixed headers stay where they were.

Back where it was

The scroll position survives the lock, and comes back at once on release, even with scroll-behavior: smooth.

Works on iPhone

Mobile Safari ignores overflow: hidden. On iOS the lock blocks page touches and keeps inputs above the keyboard instead.

Follows your dialogs

data-scroll-lock on a dialog, details, popover or any element locks while it is open and releases when it closes or leaves.

Visible to CSS

data-scroll-lock-state marks the locked page and each element that holds a lock, ready for backdrops and transitions.

02 / Fit it into your stack

An attribute first. A function when you need it.

Without JavaScript the page simply keeps scrolling; nothing breaks.

Package

@samline/scroll-lock

lockScroll, createScrollLock, scrollLock and autoScrollLock as ESM or CommonJS.

One lock

lockScroll(options)

Returns the release, safe to call twice.

Whole page

autoScrollLock(options)

Every [data-scroll-lock], including elements added later.

HTML / CDN

window.ScrollLock

A classic script that starts on its own.

Per component

createScrollLock(options)

lock, unlock and toggle without double releases.

Styling

No stylesheet

Style the locked page with data-scroll-lock-state.

03 / Install and lock

One attribute. One call.

Lock the page behind a modal dialog while it is open.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/scroll-lock

pnpm

Terminal
pnpm add @samline/scroll-lock

yarn

Terminal
yarn add @samline/scroll-lock

bun

Terminal
bun add @samline/scroll-lock

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js" defer></script>
2

Mark the dialog

data-scroll-lock on a dialog, details, popover or any element that shows and hides.

index.html
<button type="button" id="open">Read the terms</button>

<dialog id="terms" data-scroll-lock>
  <p>…</p>
  <form method="dialog"><button>Close</button></form>
</dialog>
3

Start it

main.js
import { autoScrollLock } from '@samline/scroll-lock'

autoScrollLock()

document.querySelector('#open').addEventListener('click', () => {
  document.querySelector('#terms').showModal()
})
Copy complete working files

Continue with every option, the attributes and how iOS is handled.

Explore the options
04 / Beyond dialogs

One lock.
Every kind of overlay.

Three common jobs, without touching overflow yourself.

lockScroll()

Lock from your code

Hold the release, call it once.

Read the API
main.js
const unlock = lockScroll()

drawer.addEventListener('close', unlock, { once: true })
--scroll-lock-gap

Keep a fixed header still

Pad it by the removed scrollbar.

Read the options
style.css
.header {
  padding-right: var(--scroll-lock-gap, 0px);
}
createScrollLock

Toggle a menu

One lock per component.

Read the API
main.js
const lock = createScrollLock()

button.addEventListener('click', () => {
  menu.hidden = !menu.hidden
  lock.toggle(!menu.hidden)
})
Explore working examples
05 / Before you build

A few details. Clearly answered.

Why not just overflow: hidden on the body?
It works on desktop until two overlays share it, the scrollbar disappears and the page shifts, or the page sets overflow on html. On iPhone it does not stop scrolling at all.
Does it work without a bundler?
Yes. Load dist/browser/scroll-lock.global.js; it watches [data-scroll-lock] on its own, and ScrollLock.lock() and ScrollLock.unlock() work from inline handlers. Pin the version in production.
What does it do on iOS Safari?
It blocks touch scrolling outside scrollable areas, stops scrollable areas from handing the scroll to the page at their edges, and keeps focused inputs above the keyboard, then restores the position on release.
Does it trap focus or hide the background from screen readers?
No. It only stops scrolling. showModal() on a dialog already traps focus and makes the rest of the page inert; use it, or inert, for custom overlays.
What if two components lock at once?
Each lock counts. The page unlocks only after every lock is released, and releasing the same lock twice does nothing.
Will my page jump when the scrollbar disappears?
No. Its width is added to the body padding, and to --scroll-lock-gap for fixed elements. With scrollbar-gutter: stable nothing needs to move.
What happens without JavaScript?
The page keeps scrolling behind the overlay, as it would without the package. Nothing is hidden or broken.
Do dialogs added later work?
Yes. autoScrollLock watches the page, locks for elements added at any time, and releases the lock of elements that are removed while open.
Scroll, held still

Every overlay, a steady page.

Try the examples or follow the first steps.

Guides, the complete API and release notes, in one place.

Read the documentation