- Docs
- API reference
API reference
Every @samline/scroll-lock export, lockScroll, createScrollLock, scrollLock, autoScrollLock, their types and the window.ScrollLock global.
lockScroll(options?)
lockScroll(options?: ScrollLockOptions): () => void
Locks the page and returns the release. See Options.
import { lockScroll } from '@samline/scroll-lock'
const unlock = lockScroll()
drawer.addEventListener('close', unlock, { once: true })
Locks nest: the page unlocks after the last release, in any order. Calling a release twice does nothing. Without a DOM it returns a no-op. It is also the default export of @samline/scroll-lock/vanilla.
createScrollLock(options?)
createScrollLock(options?: ScrollLockOptions): ScrollLock
interface ScrollLock {
lock(): void
unlock(): void
toggle(force?: boolean): void
isLocked(): boolean
destroy(): void
}
A controller that holds at most one lock. lock() while locked and unlock() while unlocked do nothing, so a component can call them on every open and close without counting. toggle(true) locks, toggle(false) unlocks. destroy() releases the lock and ignores later lock() calls; it is idempotent.
scrollLock(target, options?)
scrollLock(target: Element | string | Iterable<Element> | ArrayLike<Element>, options?: ScrollLockWatchOptions): ScrollLockController
interface ScrollLockWatchOptions extends ScrollLockOptions {
isOpen?: (element: Element) => boolean
}
interface ScrollLockController {
refresh(): void
isLocked(): boolean
destroy(): void
}
Locks the page while an element is open. Each element holds its own lock, so several watched elements unlock in any order. An element counts as open when:
<dialog>and<details>: it has theopenattribute.[popover]: it matches:popover-open.- Any other element: it has no
hiddenattribute and noaria-hidden="true". - With
isOpen, whatever your function returns.
Changes to open, hidden, aria-hidden, class, style, the data-scroll-lock-* attributes and the toggle event are picked up on their own. Call refresh() after changing anything else your isOpen reads. Each element gets data-scroll-lock-state="locked" or "unlocked". destroy() releases the locks, stops watching and restores the state attribute; it is idempotent. Call it before removing a watched element from the page; autoScrollLock does that for you.
autoScrollLock(options?)
autoScrollLock(options?: AutoScrollLockOptions): { refresh(): void; destroy(): void }
interface AutoScrollLockOptions extends ScrollLockWatchOptions {
root?: ParentNode
observe?: boolean
}
Watches every [data-scroll-lock] element inside root (the document by default), as scrollLock does. With observe (the default), elements added later are watched too, and the lock of an element removed from the page is released. refresh() picks up elements added while observe is false.
isScrollLocked()
isScrollLocked(): boolean
true while any lock is held, by any function of the package.
resetScrollLock()
resetScrollLock(): void
Releases every lock at once, for example after a client-side navigation unmounted an overlay without its cleanup. Controllers that held a lock report isLocked() === false and can lock again; watched elements get data-scroll-lock-state="unlocked" and lock again on their next change.
isOpenElement(element)
isOpenElement(element: Element): boolean
The default isOpen of scrollLock, exported to build on: isOpen: el => isOpenElement(el) && !el.classList.contains('closing').
Platform helpers and constants
| Export | Value |
|---|---|
ATTRIBUTE |
'data-scroll-lock' |
STATE_ATTRIBUTE |
'data-scroll-lock-state' |
GAP_PROPERTY |
'--scroll-lock-gap' |
DEFAULTS |
{ mode: 'auto', reserveGap: true, positionFixed: 'never' } |
MODES, POSITION_FIXED |
The accepted values of mode and positionFixed. |
resolveOptions(options) |
Options merged over DEFAULTS. |
isIOS(info), isSafari(info) |
Pure checks on { userAgent, platform, maxTouchPoints, standalone }. |
resolveMode(mode, info) |
'overflow' or 'ios': what mode stands for on that platform. |
usesPositionFixed(value, info) |
Whether positionFixed pins the body on that platform. |
Types
ScrollLockOptions, ScrollLockMode, PositionFixed, PlatformInfo, ScrollLock, ScrollLockWatchOptions, AutoScrollLockOptions and ScrollLockController.
window.ScrollLock
The browser bundle (dist/browser/scroll-lock.global.js) defines window.ScrollLock and runs autoScrollLock() once the DOM is ready, unless the script tag has data-manual.
| Member | Purpose |
|---|---|
lockScroll, createScrollLock, scrollLock, autoScrollLock, isScrollLocked, resetScrollLock |
The functions above. |
lock(), unlock() |
One shared lock for inline handlers. lock() twice still needs one unlock(). |
auto(options?) |
Start (or restart) watching [data-scroll-lock]. Returns the controller. |
controller |
The controller of the automatic run, or null. |