(null);
const [, setLocked] = useScrollLock(scroller);
return (
{children}
);
}
```
Same hook, same tuple. This is why `target` is required rather than defaulting to `document.body`: the library can't know which element is your scroll root.
### 3. Lock during a drag
Touch-dragging a slider, a sortable list, or a custom carousel scrolls the page unless something stops it — and a `touchmove` guard is exactly the right tool:
```tsx
const [, setLocked] = useScrollLock(() => document.body);
setLocked(true)}
onPointerUp={() => setLocked(false)}
onPointerCancel={() => setLocked(false)}
/>
```
`onPointerCancel` matters: the browser can steal the pointer mid-gesture, and without it you'd leave the page locked. If you're building the drag itself rather than wiring one up, [`useDraggable`](https://reactuse.com/element/usedraggable/) already handles the pointer bookkeeping.
## Gotchas Worth Knowing
### 1. The lock is a style, not a lifecycle
The lock is an inline `overflow: hidden` written onto an element the hook doesn't own, so something has to put it back. Since `@reactuses/core` v6.5.3 the hook does that itself when the owning component unmounts: it restores the exact inline value it replaced and detaches the iOS `touchmove` guard, so a route change with the modal still open can no longer leave the page frozen. On v6.5.2 and earlier it didn't — worth knowing if you're pinned to an older version, because on iOS the leftover `passive: false` listener kills touch scrolling for the rest of the session, not just the style.
Unmounting is only half of it. The other half — the modal closing while the component stays mounted — is yours either way, which is exactly why the pattern above binds `setLocked` to `open` with a cleanup instead of toggling it from two handlers:
```tsx
useEffect(() => {
setLocked(open);
return () => setLocked(false);
}, [open, setLocked]);
```
Think of the setter as owning a style you borrowed. Every borrow needs a return.
### 2. One owner per element
Two hook instances locking the same element is the subtlest failure mode, because each keeps its *own* memory of the original `overflow`:
```text
A.lock() → overflow: hidden (A remembered "auto")
B.lock() → overflow: hidden (B remembered "hidden" 😬)
A.unlock() → overflow: auto (page scrolls, though B still thinks it's locked)
B.unlock() → overflow: hidden (page is now stuck, with nothing open)
```
Nothing is going to save you here — this is inherent to "save the old value, put it back" and applies to every hand-rolled lock and most libraries. The answer is architectural: **one lock owner per element.** Put the `useScrollLock(() => document.body)` call in your layout, provider, or store, and let modals ask it to lock rather than each carrying its own.
### 3. `initialState: true` skips the iOS guard
`useScrollLock(target, true)` applies `overflow: hidden` from the first commit — but the `touchmove` listener is only attached inside `lock()`, which never ran. So a page that starts locked is still rubber-band-scrollable on iOS. Start `false` and flip it:
```tsx
const [, setLocked] = useScrollLock(() => document.body);
useEffect(() => { setLocked(true); }, [setLocked]); // locked from mount, guard included
```
### 4. Desktop layout shift
Hiding the scrollbar reclaims ~15px and the entire page shifts sideways. That's not the hook's job to fix, and it's one CSS line:
```css
html { scrollbar-gutter: stable; }
```
### 5. Pass a getter, not `document.body`, for SSR
`useScrollLock(document.body)` evaluates `document.body` **during render**, which throws on the server before the hook gets a chance to be careful. `() => document.body` (or a ref) is only read inside effects and handlers, where `getTargetElement` already bails out without a `window`:
```tsx
const [, setLocked] = useScrollLock(() => document.body); // ✅ SSR-safe
const [, setLocked] = useScrollLock(document.body); // ❌ crashes on the server
```
The same rule applies to every hook in the library that takes an element target, and it's the single most common SSR mistake in Next.js and Remix apps.
### 6. `hidden` stops gestures, not programmatic scrolling
An `overflow: hidden` box is still scrollable via `scrollTop`, `scrollTo`, `scrollIntoView` — and, crucially, by the browser scrolling a newly focused element into view. If focus escapes to a link behind your modal, your "locked" page will scroll to it. Scroll locking and focus trapping are two halves of the same feature; ship both.
## When Not to Use useScrollLock
- **You only need to stop an inner scroller from chaining to the page** → `overscroll-behavior: contain` in CSS, no JavaScript at all.
- **You're using `