keys/hooks/use-scroll-lock

useScrollLock

standalonescrollutility

Prevent body or element scrolling with reference counting. Multiple locks on the same element stack.

useScrollLock prevents an element from scrolling while it is enabled, then restores the previous overflow when released. Locks are reference-counted per element, so two overlays can lock document.body independently and scrolling is only restored once both release. It is standalone (no provider) and ships as a copy-paste utility hook.

tsx

1 useScrollLock({ enabled: open })

When to use it

Freeze background scroll behind a modal, drawer, sheet, or full-screen overlay.
Lock a specific scroll container (pass target) rather than the whole page.

Pair it with useFocusTrap to hold focus inside a modal while its background is locked.

Limitations

useScrollLock toggles overflow: hidden on the target element with refcounted restore. It also compensates for scrollbar width with padding-right and marks the locked element with data-scroll-locked. It does not implement the full react-remove-scroll / Radix useScrollLock parity surface:

Defaults to the host document.body. In multi-window or iframe setups, capture the trigger's owner document after mount and pass a ref to that document's body:
tsx
```
const triggerRef = useRef<HTMLButtonElement>(null);
const bodyRef = useRef<HTMLElement | null>(null);

useEffect(() => {
  bodyRef.current = triggerRef.current?.ownerDocument.body ?? null;
});

useScrollLock({ target: bodyRef, enabled: open });
```
Mount order matters: register the effect before calling useScrollLock so the target ref is populated before the lock effect runs.
No iOS Safari rubber-band guard. Setting overflow: hidden on body does not stop iOS touch scrolling. The page can still pan-scroll on iOS while the lock is active.

iOS rubber-band compensation is not part of the current surface; use a dedicated touch-scroll guard when that behavior matters.

Installation

$pnpm exec dgadd add keys/scroll-lock

[Installs to]src/hooks/use-scroll-lock.ts[Item]keys/scroll-lock

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
target	RefObject<HTMLElement \| null>	—	Ref to the element to lock. Defaults to document.body when omitted.
enabled	boolean	true	Whether the scroll lock is active.

Returns

voidThis hook does not return a value.

Examples

Lock body scroll in a modal

Preview

tsx

1 "use client";2 3 import { useScrollLock } from "@diffgazer/keys";4 import { type RefObject, useRef, useState } from "react";5 6 function Overlay({7   onClose,8   panelRef,9 }: {10   onClose: () => void;11   panelRef: RefObject<HTMLDivElement | null>;12 }) {13   useScrollLock({ target: panelRef });14 15   return (16     <div17       style={{18         position: "absolute",19         inset: 0,20         display: "flex",21         alignItems: "center",22         justifyContent: "center",23         zIndex: 50,24       }}25     >26       <button27         type="button"28         aria-label="Close overlay"29         onClick={onClose}30         style={{31           position: "absolute",32           inset: 0,33           border: "none",34           padding: 0,35           background: "rgba(0,0,0,0.6)",36           cursor: "pointer",37         }}38       />39       <div style={{ position: "relative", padding: 16, background: "white", color: "black" }}>40         <h3>Overlay</h3>41         <p>Panel scroll is locked while this overlay is visible.</p>42         <button type="button" onClick={onClose}>43           Close44         </button>45       </div>46     </div>47   );48 }49 50 export default function UseScrollLockBasic() {51   const panelRef = useRef<HTMLDivElement>(null);52   const [open, setOpen] = useState(false);53 54   return (55     <div56       ref={panelRef}57       style={{58         height: 200,59         overflow: "auto",60         border: "1px solid currentColor",61         padding: 8,62       }}63     >64       <p>Scroll status: {open ? "locked" : "unlocked"}</p>65       <button type="button" onClick={() => setOpen(true)}>66         Show Overlay67       </button>68       <p>Scroll inside this panel, then open the overlay to lock it.</p>69       {Array.from({ length: 12 }, (_, index) => `Scrollable row ${index + 1}`).map((row) => (70         <p key={row} style={{ margin: "4px 0" }}>71           {row}72         </p>73       ))}74       {open && <Overlay onClose={() => setOpen(false)} panelRef={panelRef} />}75     </div>76   );77 }78

Lock a specific scroll container

Preview

tsx

1 "use client";2 3 import { useScrollLock } from "@diffgazer/keys";4 import { useRef, useState } from "react";5 6 export default function UseScrollLockTarget() {7   const scrollRef = useRef<HTMLDivElement>(null);8   const [locked, setLocked] = useState(false);9 10   // Lock a specific scroll container instead of document.body.11   useScrollLock({ target: scrollRef, enabled: locked });12 13   return (14     <div>15       <button type="button" onClick={() => setLocked((v) => !v)}>16         {locked ? "Unlock panel" : "Lock panel"}17       </button>18 19       <div20         ref={scrollRef}21         style={{22           marginTop: 8,23           height: 120,24           overflow: "auto",25           border: "1px solid currentColor",26           padding: 8,27         }}28       >29         {Array.from({ length: 20 }, (_, i) => `Scrollable row ${i + 1}`).map((row) => (30           <p key={row} style={{ margin: "4px 0" }}>31             {row}32           </p>33         ))}34       </div>35       <p>Scrolling inside the panel is blocked while locked; the page itself is untouched.</p>36     </div>37   );38 }39

Notes

Reference counting

Multiple useScrollLock calls on the same element increment a shared counter. Scrolling is only restored when all locks are released, preventing double-unlock bugs.

Standalone

useScrollLock does not require KeyboardProvider. It works independently as a copy-paste utility hook.

Edge cases

Toggling enabled. Flipping enabled to false releases this hook's lock immediately; the element stays locked while any other lock remains.

useFocusTrap — trap focus inside the modal whose background you lock.
Focus and scroll guide — composing scroll lock with focus management.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.