Skip to Content
Zayne UI Logo

Zayne UI

Scroll Lock

Lock page scroll while keeping scroll inside a specific element (modals, drawers, overlays).

The ScrollLock component locks page scrolling while it is mounted, but still lets the user scroll inside the element it renders (and any shards you pass). It removes the page scrollbar without layout shift by compensating for the scrollbar's width.

It is a component wrapper around the useScrollLock hook from @zayne-labs/toolkit-react, and follows the same API as RemoveScroll from react-remove-scroll.

Installation

npm install @zayne-labs/ui-react

Preview

Loading...

Basic Usage

ScrollLock renders a div by default. Scrolling is allowed inside that element and blocked everywhere else.

import { ScrollLock } from "@zayne-labs/ui-react/common/scroll-lock";

function Modal({ children }) {
	return (
		<div className="fixed inset-0 bg-black/50">
			<ScrollLock className="max-h-[80dvh] overflow-y-auto">{children}</ScrollLock>
		</div>
	);
}

Toggle with enabled

Instead of unmounting, you can turn the lock on and off with enabled.

<ScrollLock enabled={isOpen} className="overflow-y-auto">
	<DrawerContent />
</ScrollLock>

Without a wrapper element

Use asChild to merge the lock (props and ref) onto your own element instead of rendering a wrapper. This is the equivalent of forwardProps in react-remove-scroll.

<ScrollLock asChild={true}>
	<aside className="overflow-y-auto">...</aside>
</ScrollLock>

Shards

Shards are extra elements that stay scrollable and interactive while the lock is active. Use them for things rendered outside the lock, like a toast region or a teleported popover.

function App() {
	const toastRegionRef = useRef<HTMLDivElement>(null);

	return (
		<ScrollLock shards={[toastRegionRef]}>
			<DialogContent />
		</ScrollLock>
	);
}

Options

PropDefaultDescription
enabledtrueWhether the lock is active.
removeScrollBartrueHide the page scrollbar (and compensate for its width).
gapMode"margin"Compensate for the removed scrollbar with margin-right or padding-right on body.
inertfalseBlock pointer interactions outside the lock and shards, not just scrolling.
noIsolationfalseOnly lock the page scroll; don't block scroll events outside the lock.
allowPinchZoomfalseAllow pinch-zoom (and ctrl + wheel zoom) while locked.
noRelativefalseDon't set position: relative on body while locked.
shards—Extra elements (refs, elements or getters) that stay scrollable while locked.

Component Source

"use client";import { useComposeRefs, useScrollLock, type UseScrollLockOptions } from "@zayne-labs/toolkit-react";import type { PolymorphicPropsStrict } from "@zayne-labs/toolkit-react/utils";import { useRef } from "react";import { Slot } from "../slot";export type ScrollLockProps = Omit<UseScrollLockOptions, "ref"> & {	/**	 * Apply the lock to the child element instead of rendering a wrapper `div`.	 */	asChild?: boolean;	children?: React.ReactNode;	/**	 * Ref to the rendered element	 */	ref?: React.Ref<HTMLElement>;};/** * @description Stops the page from scrolling while mounted. Scrolling still works inside this element and any `shards`. * * @example * ```tsx * <ScrollLock enabled={isOpen} className="fixed inset-0 overflow-y-auto"> *   <DialogContent /> * </ScrollLock> * ``` */function ScrollLock<TElement extends React.ElementType = "div">(	props: PolymorphicPropsStrict<TElement, ScrollLockProps>) {	const {		allowPinchZoom,		as: Element = "div",		asChild,		enabled = true,		gapMode,		inert,		noIsolation,		noRelative,		ref: forwardedRef,		removeScrollBar,		shards,		...restOfProps	} = props;	const lockRef = useRef<HTMLElement>(null);	useScrollLock({		allowPinchZoom,		enabled,		gapMode,		inert,		noIsolation,		noRelative,		ref: lockRef,		removeScrollBar,		shards,	});	const ref = useComposeRefs(lockRef, forwardedRef);	const Component = asChild ? Slot.Root : Element;	return <Component ref={ref} {...restOfProps} />;}export { ScrollLock };

Component API

Multiple locks can be active at once (for example, nested dialogs). The most recently activated lock controls scroll isolation, and the page stays locked until every lock is released.

Edit on GitHub

Last updated on