Usage
Locks page scroll while active and keeps the page where it is. The page gets overflow: hidden (on the root, or on body when its own overflow is the one the viewport uses), which stops wheel, keyboard and scrollbar scrolling, and overscroll-behavior-y: none on the root and body, which turns off pull-to-refresh (Chrome on Android) while the lock holds. On touch screens a one-finger pan that would scroll the page is cancelled, because iOS Safari before 26.4 scrolls an overflow: hidden page under a finger; pans that a scroller inside the overlay can take, drags on a native range input, pinch-zoom, and one-finger drags on a pinch-zoomed page (which pan the zoomed view) still work. The scroll offset never changes, so nothing jumps when the lock starts or ends, and iOS Safari keeps its toolbar as it was. Where the hidden scrollbar takes layout space (desktop), the hook holds its gutter open with scrollbar-gutter: stable, so the page, including any position: fixed chrome, does not shift sideways.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Use when opening full-screen modals or dialogs to prevent background content from scrolling. |
| Do | Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter. |
| Don't | Use for non-modal overlays like popovers or tooltips; users should be able to scroll away from those. |
Parameters
| Param | Type | Description |
|---|---|---|
isLockedrequired | boolean | whether page scroll should be locked. |
Use with shadcn
Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.
This install URL expires with the draft preview.bash