- Docs
- Getting started
Getting started
Install @samline/scroll-lock with a package manager or a script tag and lock the page behind your first modal dialog.
Install @samline/scroll-lock, then follow the Package / ESM or the HTML / CDN path to the first lock. Both use the same API.
Requirements
- Any modern browser. Without JavaScript the page keeps scrolling, as it would without the package.
- On the server, every function does nothing and
isScrollLocked()isfalse. - No runtime dependencies.
Install
npm
npm install @samline/scroll-lockpnpm
pnpm add @samline/scroll-lockyarn
yarn add @samline/scroll-lockbun
bun add @samline/scroll-lockHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js" defer></script>Package / ESM
import { autoScrollLock } from '@samline/scroll-lock'
autoScrollLock()
document.querySelector('#open').addEventListener('click', () => {
document.querySelector('#terms').showModal()
})
<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>
autoScrollLock() watches every [data-scroll-lock] element, including elements added later, and locks the page while one is open. It returns { refresh, destroy }. To lock from your own code, const unlock = lockScroll(). Available as ESM and CommonJS (require('@samline/scroll-lock')). There is no stylesheet.
HTML / CDN
For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It watches [data-scroll-lock] as soon as the DOM is ready. Pin the version in production.
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js"
defer
></script>
ScrollLock.lock() and ScrollLock.unlock() hold one shared lock for inline handlers. To pass options, add data-manual to the script tag and start it yourself:
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js"
data-manual
defer
></script>
<script type="module">
ScrollLock.auto({ positionFixed: 'safari' })
</script>
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
data-scroll-lock on the dialog locks the page while it is open and releases it however it closes: the close button, the form, Escape or a click outside. The list inside still scrolls.
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Lock the page behind a modal dialog</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<button type="button" id="open" aria-haspopup="dialog">Read the terms</button>
<dialog id="terms" data-scroll-lock closedby="any" aria-labelledby="terms-title">
<div class="header">
<h2 id="terms-title">Terms</h2>
<form method="dialog">
<button class="close" aria-label="Close the terms">
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path
d="M6 6l12 12M18 6L6 18"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
/>
</svg>
</button>
</form>
</div>
<div class="list" tabindex="0" role="region" aria-label="Clauses">
<p>Clause 1.</p>
<p>Clause 2.</p>
<p>Clause 3.</p>
<p>Clause 4.</p>
<p>Clause 5.</p>
<p>Clause 6.</p>
<p>Clause 7.</p>
<p>Clause 8.</p>
<p>Clause 9.</p>
<p>Clause 10.</p>
<p>Clause 11.</p>
<p>Clause 12.</p>
</div>
<form method="dialog"><button>Accept</button></form>
</dialog>
<div class="page">
<section><h2>Section 1</h2></section>
<section><h2>Section 2</h2></section>
<section><h2>Section 3</h2></section>
<section><h2>Section 4</h2></section>
<section><h2>Section 5</h2></section>
<section><h2>Section 6</h2></section>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.page {
padding: 1rem 1.5rem;
}
section {
min-height: 60vh;
border-top: 1px solid #ddd;
}
.close {
display: grid;
place-items: center;
width: 2rem;
height: 2rem;
padding: 0;
border: 1px solid #ddd;
border-radius: 50%;
background: #fff;
cursor: pointer;
}
.header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 1rem;
}
#open {
position: fixed;
top: 1rem;
right: 1rem;
}
dialog {
width: min(28rem, calc(100vw - 2rem));
box-sizing: border-box;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.4);
}
.list {
max-height: 12rem;
overflow-y: auto;
overscroll-behavior: contain;
}
JavaScript
// The bundle already watches [data-scroll-lock].
const dialog = document.querySelector('#terms')
document.querySelector('#open').addEventListener('click', () => dialog.showModal())
// Light dismiss where closedby="any" is not supported yet (Safari).
if (!('closedBy' in HTMLDialogElement.prototype)) {
dialog.addEventListener('click', event => {
if (event.target !== dialog) return
const box = dialog.getBoundingClientRect()
const inside =
event.clientX >= box.left &&
event.clientX <= box.right &&
event.clientY >= box.top &&
event.clientY <= box.bottom
if (!inside) dialog.close()
})
}
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Lock the page behind a modal dialog</title>
<style>
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.page {
padding: 1rem 1.5rem;
}
section {
min-height: 60vh;
border-top: 1px solid #ddd;
}
.close {
display: grid;
place-items: center;
width: 2rem;
height: 2rem;
padding: 0;
border: 1px solid #ddd;
border-radius: 50%;
background: #fff;
cursor: pointer;
}
.header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 1rem;
}
#open {
position: fixed;
top: 1rem;
right: 1rem;
}
dialog {
width: min(28rem, calc(100vw - 2rem));
box-sizing: border-box;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.4);
}
.list {
max-height: 12rem;
overflow-y: auto;
overscroll-behavior: contain;
}
</style>
</head>
<body>
<main>
<button type="button" id="open" aria-haspopup="dialog">Read the terms</button>
<dialog id="terms" data-scroll-lock closedby="any" aria-labelledby="terms-title">
<div class="header">
<h2 id="terms-title">Terms</h2>
<form method="dialog">
<button class="close" aria-label="Close the terms">
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path
d="M6 6l12 12M18 6L6 18"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
/>
</svg>
</button>
</form>
</div>
<div class="list" tabindex="0" role="region" aria-label="Clauses">
<p>Clause 1.</p>
<p>Clause 2.</p>
<p>Clause 3.</p>
<p>Clause 4.</p>
<p>Clause 5.</p>
<p>Clause 6.</p>
<p>Clause 7.</p>
<p>Clause 8.</p>
<p>Clause 9.</p>
<p>Clause 10.</p>
<p>Clause 11.</p>
<p>Clause 12.</p>
</div>
<form method="dialog"><button>Accept</button></form>
</dialog>
<div class="page">
<section><h2>Section 1</h2></section>
<section><h2>Section 2</h2></section>
<section><h2>Section 3</h2></section>
<section><h2>Section 4</h2></section>
<section><h2>Section 5</h2></section>
<section><h2>Section 6</h2></section>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-lock@1.0.0/dist/browser/scroll-lock.global.js"></script>
<script>
// The bundle already watches [data-scroll-lock].
const dialog = document.querySelector('#terms')
document.querySelector('#open').addEventListener('click', () => dialog.showModal())
// Light dismiss where closedby="any" is not supported yet (Safari).
if (!('closedBy' in HTMLDialogElement.prototype)) {
dialog.addEventListener('click', event => {
if (event.target !== dialog) return
const box = dialog.getBoundingClientRect()
const inside =
event.clientX >= box.left &&
event.clientX <= box.right &&
event.clientY >= box.top &&
event.clientY <= box.bottom
if (!inside) dialog.close()
})
}
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Lock the page behind a modal dialog</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<button type="button" id="open" aria-haspopup="dialog">Read the terms</button>
<dialog id="terms" data-scroll-lock closedby="any" aria-labelledby="terms-title">
<div class="header">
<h2 id="terms-title">Terms</h2>
<form method="dialog">
<button class="close" aria-label="Close the terms">
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path
d="M6 6l12 12M18 6L6 18"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
/>
</svg>
</button>
</form>
</div>
<div class="list" tabindex="0" role="region" aria-label="Clauses">
<p>Clause 1.</p>
<p>Clause 2.</p>
<p>Clause 3.</p>
<p>Clause 4.</p>
<p>Clause 5.</p>
<p>Clause 6.</p>
<p>Clause 7.</p>
<p>Clause 8.</p>
<p>Clause 9.</p>
<p>Clause 10.</p>
<p>Clause 11.</p>
<p>Clause 12.</p>
</div>
<form method="dialog"><button>Accept</button></form>
</dialog>
<div class="page">
<section><h2>Section 1</h2></section>
<section><h2>Section 2</h2></section>
<section><h2>Section 3</h2></section>
<section><h2>Section 4</h2></section>
<section><h2>Section 5</h2></section>
<section><h2>Section 6</h2></section>
</div>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.page {
padding: 1rem 1.5rem;
}
section {
min-height: 60vh;
border-top: 1px solid #ddd;
}
.close {
display: grid;
place-items: center;
width: 2rem;
height: 2rem;
padding: 0;
border: 1px solid #ddd;
border-radius: 50%;
background: #fff;
cursor: pointer;
}
.header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 1rem;
}
#open {
position: fixed;
top: 1rem;
right: 1rem;
}
dialog {
width: min(28rem, calc(100vw - 2rem));
box-sizing: border-box;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.4);
}
.list {
max-height: 12rem;
overflow-y: auto;
overscroll-behavior: contain;
}
JavaScript
import { autoScrollLock } from '@samline/scroll-lock'
autoScrollLock()
const dialog = document.querySelector('#terms')
document.querySelector('#open').addEventListener('click', () => dialog.showModal())
// Light dismiss where closedby="any" is not supported yet (Safari).
if (!('closedBy' in HTMLDialogElement.prototype)) {
dialog.addEventListener('click', event => {
if (event.target !== dialog) return
const box = dialog.getBoundingClientRect()
const inside =
event.clientX >= box.left &&
event.clientX <= box.right &&
event.clientY >= box.top &&
event.clientY <= box.bottom
if (!inside) dialog.close()
})
}
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Lock the page behind a modal dialog</title>
<style>
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.page {
padding: 1rem 1.5rem;
}
section {
min-height: 60vh;
border-top: 1px solid #ddd;
}
.close {
display: grid;
place-items: center;
width: 2rem;
height: 2rem;
padding: 0;
border: 1px solid #ddd;
border-radius: 50%;
background: #fff;
cursor: pointer;
}
.header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 1rem;
}
#open {
position: fixed;
top: 1rem;
right: 1rem;
}
dialog {
width: min(28rem, calc(100vw - 2rem));
box-sizing: border-box;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.4);
}
.list {
max-height: 12rem;
overflow-y: auto;
overscroll-behavior: contain;
}
</style>
</head>
<body>
<main>
<button type="button" id="open" aria-haspopup="dialog">Read the terms</button>
<dialog id="terms" data-scroll-lock closedby="any" aria-labelledby="terms-title">
<div class="header">
<h2 id="terms-title">Terms</h2>
<form method="dialog">
<button class="close" aria-label="Close the terms">
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path
d="M6 6l12 12M18 6L6 18"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
/>
</svg>
</button>
</form>
</div>
<div class="list" tabindex="0" role="region" aria-label="Clauses">
<p>Clause 1.</p>
<p>Clause 2.</p>
<p>Clause 3.</p>
<p>Clause 4.</p>
<p>Clause 5.</p>
<p>Clause 6.</p>
<p>Clause 7.</p>
<p>Clause 8.</p>
<p>Clause 9.</p>
<p>Clause 10.</p>
<p>Clause 11.</p>
<p>Clause 12.</p>
</div>
<form method="dialog"><button>Accept</button></form>
</dialog>
<div class="page">
<section><h2>Section 1</h2></section>
<section><h2>Section 2</h2></section>
<section><h2>Section 3</h2></section>
<section><h2>Section 4</h2></section>
<section><h2>Section 5</h2></section>
<section><h2>Section 6</h2></section>
</div>
</main>
<script type="module">
import { autoScrollLock } from '@samline/scroll-lock'
autoScrollLock()
const dialog = document.querySelector('#terms')
document.querySelector('#open').addEventListener('click', () => dialog.showModal())
// Light dismiss where closedby="any" is not supported yet (Safari).
if (!('closedBy' in HTMLDialogElement.prototype)) {
dialog.addEventListener('click', event => {
if (event.target !== dialog) return
const box = dialog.getBoundingClientRect()
const inside =
event.clientX >= box.left &&
event.clientX <= box.right &&
event.clientY >= box.top &&
event.clientY <= box.bottom
if (!inside) dialog.close()
})
}
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of every function and window.ScrollLock.
Options, attributes, the state attribute and --scroll-lock-gap.
Nesting, the scrollbar gap, iOS Safari and positionFixed.