API Reference

Complete reference for all functions and types in the @hunterliu/scroll-lock library.

Functions

lockScroll(target)

Locks scroll on the specified target element. Multiple calls on the same element use reference counting.

function lockScroll(target: ScrollLockTarget): LockState | undefined;

Parameters:

• target: ScrollLockTarget - Element to lock (default: document.body if null/undefined)

Returns:

• LockState | undefined - The lock state object, or undefined if not in browser environment

Example:

import { lockScroll } from "@hunterliu/scroll-lock";

// Lock body scroll (pass null/undefined for default)
lockScroll(document.body);

// Lock specific element
const modal = document.querySelector(".modal");
lockScroll(modal);

// Lock using window (targets documentElement)
lockScroll(window);

unlockScroll(target, options?)

Unlocks scroll on the specified target element. Uses reference counting unless forced.

function unlockScroll(
  target: ScrollLockTarget,
  options?: {
    force?: boolean;
  },
): LockState | undefined;

Parameters:

• target: ScrollLockTarget - Element to unlock (default: document.body if null/undefined)
• options? - Optional configuration object
  • force?: boolean - Bypass reference counting (default: false)

Returns:

• LockState | undefined - The lock state object, or undefined if not in browser environment

Example:

import { unlockScroll } from "@hunterliu/scroll-lock";

// Normal unlock (respects reference counting)
unlockScroll(document.body);

// Force unlock (ignores reference count)
unlockScroll(document.body, { force: true });

// Unlock specific element
unlockScroll(modal);

isScrollLocked(target)

Checks if the specified target element is currently locked by this library.

function isScrollLocked(target: ScrollLockTarget): boolean;

Parameters:

• target: ScrollLockTarget - Element to check (default: document.body if null/undefined)

Returns:

• boolean - true if the element is locked, false otherwise

Example:

import { isScrollLocked, lockScroll } from "@hunterliu/scroll-lock";

console.log(isScrollLocked(document.body)); // false

lockScroll(document.body);
console.log(isScrollLocked(document.body)); // true

// Check specific element
const modal = document.querySelector(".modal");
console.log(isScrollLocked(modal)); // false

clearAllScrollLocks()

Immediately clears all scroll locks on all targets, restoring their original styles.

function clearAllScrollLocks(): void;

Example:

import { clearAllScrollLocks, lockScroll } from "@hunterliu/scroll-lock";

// Lock multiple elements
lockScroll(document.body);
lockScroll(document.querySelector(".modal"));
lockScroll(document.querySelector(".sidebar"));

// Clear all locks at once
clearAllScrollLocks();

Types

ScrollLockTarget

Union type defining valid targets for scroll locking operations.

type ScrollLockTarget =
  | HTMLElement
  | SVGElement
  | Window
  | Document
  | null
  | undefined;

Target Resolution:

• HTMLElement | SVGElement - Used directly as the lock target
• Window - Targets window.document.documentElement
• Document - Targets document.documentElement
• null | undefined - Defaults to document.body

LockState

Interface representing the state of a locked element.

interface LockState {
  count: number;
  originalOverflow?: string;
  stopTouchEventListener?: () => void;
}

Properties:

• count: number - Reference count for the lock
• originalOverflow?: string - Original overflow style value
• stopTouchEventListener?: () => void - Function to cleanup iOS touch event listener

Exported Constants

lockStateMap

WeakMap storing the lock state for each locked element.

export const lockStateMap: WeakMap<HTMLElement | SVGElement, LockState>;

Usage:

import { lockStateMap, lockScroll } from "@hunterliu/scroll-lock";

lockScroll(document.body);
const state = lockStateMap.get(document.body);
console.log(state?.count); // 1

lockedElementSet

Set containing all currently locked elements for iteration purposes.

export const lockedElementSet: Set<HTMLElement | SVGElement>;

Usage:

import { lockedElementSet, lockScroll } from "@hunterliu/scroll-lock";

lockScroll(document.body);
console.log(lockedElementSet.has(document.body)); // true