Guide

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() is false.
  • No runtime dependencies.

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>

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.

Modal dialogLive preview

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.

Page scrolls

Terms

Clause 1. This list scrolls; the page behind it does not.

Clause 2. This list scrolls; the page behind it does not.

Clause 3. This list scrolls; the page behind it does not.

Clause 4. This list scrolls; the page behind it does not.

Clause 5. This list scrolls; the page behind it does not.

Clause 6. This list scrolls; the page behind it does not.

Clause 7. This list scrolls; the page behind it does not.

Clause 8. This list scrolls; the page behind it does not.

Clause 9. This list scrolls; the page behind it does not.

Clause 10. This list scrolls; the page behind it does not.

Clause 11. This list scrolls; the page behind it does not.

Clause 12. This list scrolls; the page behind it does not.

Close with the button, Escape or a click outside.

Explore the code

HTML / CDN

HTML

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

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

main.js
// 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

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

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

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

main.js
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

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