React useScrollLock Hook

Ever tried to prevent scrolling in React and ended up with overflow:hidden chaos, layout shift nightmares, or broken scrollbar compensation? You know the drill—manually setting document.body.style.overflow, forgetting to restore original styles, dealing with scrollbar width calculations, handling cleanup on unmount. This free open source React useScrollLock custom hook handles all that scroll prevention complexity so you can focus on building smooth modal experiences instead of debugging layout shift edge cases in your React applications.

useScrollLock showcase

Smart scroll locking with automatic layout shift prevention:

"use client";import { useState } from "react";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useScrollLock } from "@/components/ui/shadcn-io/use-scroll-lock";export function UseScrollLockDemo() {  const [showModal, setShowModal] = useState(false);    const { isLocked, lock, unlock } = useScrollLock({    autoLock: false,  });  const handleLock = () => {    lock();    toast.success("Scroll locked! 🔒", {      description: "Page scrolling is now disabled",    });  };  const handleUnlock = () => {    unlock();    toast.success("Scroll unlocked! 🔓", {      description: "Page scrolling is now enabled",    });  };  const handleShowModal = () => {    setShowModal(true);    toast.info("Modal opened with auto-lock", {      description: "Background scroll is automatically locked",    });  };  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Scroll Lock Demo</h3>        <p className="text-sm text-muted-foreground">Prevent page scrolling control</p>      </div>            {/* Status Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Current Status</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <Badge             variant={isLocked ? "destructive" : "default"}             className="text-sm px-3 py-1"          >            {isLocked ? "🔒 Page Locked" : "🔓 Page Unlocked"}          </Badge>        </div>      </div>      {/* Manual Controls */}      <div className="space-y-2">        <Label className="text-sm font-medium">Manual Control</Label>        <div className="grid grid-cols-2 gap-2 h-10">          <Button            onClick={handleLock}            disabled={isLocked}            variant="destructive"            size="sm"            className="h-10"          >            Lock Scroll          </Button>          <Button            onClick={handleUnlock}            disabled={!isLocked}            variant="default"            size="sm"            className="h-10"          >            Unlock Scroll          </Button>        </div>      </div>      {/* Modal Demo */}      <div className="space-y-2">        <Label className="text-sm font-medium">Auto-Lock Demo</Label>        <div className="min-h-[40px] flex items-center">          <Button            onClick={handleShowModal}            variant="outline"            className="w-full h-10"          >            Open Modal (Auto-Lock)          </Button>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          {isLocked             ? "Scroll the page - it's locked!"             : "Try scrolling, then lock it"          }        </div>      </div>      {showModal && <Modal onClose={() => setShowModal(false)} />}    </div>  );}function Modal({ onClose }: { onClose: () => void }) {  // Auto-lock scroll when modal is mounted  useScrollLock();  return (    <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50 p-4">      <div className="bg-background border rounded-lg p-6 max-w-sm w-full shadow-lg">        <div className="space-y-4">          <div className="text-center space-y-2">            <h2 className="text-lg font-semibold">Modal with Auto-Lock</h2>            <Badge variant="destructive" className="text-sm px-3 py-1">              🔒 Scroll Locked            </Badge>          </div>                    <p className="text-sm text-muted-foreground text-center">            Background scrolling is automatically disabled while this modal is open. Try scrolling behind this dialog.          </p>                    <Button             onClick={onClose}            className="w-full h-10"          >            Close Modal          </Button>        </div>      </div>    </div>  );}export default UseScrollLockDemo;

"use client"import { useRef, useState, useCallback } from "react"import { useIsomorphicLayoutEffect } from "@/components/ui/kibo-ui/use-isomorphic-layout-effect"type UseScrollLockOptions = {  autoLock?: boolean  lockTarget?: HTMLElement | string  widthReflow?: boolean}type UseScrollLockReturn = {  isLocked: boolean  lock: () => void  unlock: () => void}type OriginalStyle = {  overflow: CSSStyleDeclaration["overflow"]  paddingRight: CSSStyleDeclaration["paddingRight"]}const IS_SERVER = typeof window === "undefined"export function useScrollLock(  options: UseScrollLockOptions = {},): UseScrollLockReturn {  const { autoLock = true, lockTarget, widthReflow = true } = options  const [isLocked, setIsLocked] = useState(false)  const target = useRef<HTMLElement | null>(null)  const originalStyle = useRef<OriginalStyle | null>(null)  const lock = useCallback(() => {    if (target.current) {      const { overflow, paddingRight } = target.current.style      // Save the original styles      originalStyle.current = { overflow, paddingRight }      // Prevent width reflow      if (widthReflow) {        // Use window inner width if body is the target as global scrollbar isn't part of the document        const offsetWidth =          target.current === document.body            ? window.innerWidth            : target.current.offsetWidth        // Get current computed padding right in pixels        const currentPaddingRight =          parseInt(window.getComputedStyle(target.current).paddingRight, 10) ||          0        const scrollbarWidth = offsetWidth - target.current.scrollWidth        target.current.style.paddingRight = `${scrollbarWidth + currentPaddingRight}px`      }      // Lock the scroll      target.current.style.overflow = "hidden"      setIsLocked(true)    }  }, [widthReflow])  const unlock = useCallback(() => {    if (target.current && originalStyle.current) {      target.current.style.overflow = originalStyle.current.overflow      // Only reset padding right if we changed it      if (widthReflow) {        target.current.style.paddingRight = originalStyle.current.paddingRight      }    }    setIsLocked(false)  }, [widthReflow])  useIsomorphicLayoutEffect(() => {    if (IS_SERVER) return    // Re-find the target element each time    if (lockTarget) {      target.current =        typeof lockTarget === "string"          ? document.querySelector(lockTarget)          : lockTarget    }    if (!target.current) {      target.current = document.body    }    if (autoLock) {      lock()    }    return () => {      unlock()    }  }, [autoLock, lockTarget, widthReflow, lock, unlock])  return { isLocked, lock, unlock }}export type { UseScrollLockOptions, UseScrollLockReturn }

This free open source React hook simplifies scroll management with TypeScript support for modern JavaScript applications. Whether you're building modals, drawers, or overlay components in your Next.js projects, this React hook keeps your scroll locking reliable and visually stable.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-scroll-lock.json

npx shadcn@latest add https://www.shadcn.io/registry/use-scroll-lock.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-scroll-lock.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-scroll-lock.json

Why most scroll lock implementations suck

Look, you could keep manually setting overflow:hidden and dealing with the side effects. But then you hit the scroll lock complexity—layout shifts when scrollbars disappear, broken width calculations, forgotten style restoration, race conditions with multiple overlays in React applications.

Most developers manually set document.body.style.overflow = 'hidden' without compensating for scrollbar width, causing jarring layout shifts when content jumps in TypeScript components. Or they forget to restore original styles properly when unmounting, leaving users stuck with broken scroll states. Some handle multiple overlays incorrectly, creating race conditions where unlocking one modal breaks scroll for all others in Next.js projects.

This React hook uses optimized scroll management under the hood, with automatic scrollbar width compensation and proper style restoration in JavaScript applications. The browser handles all the overflow logic, plus you get comprehensive cleanup and layout shift prevention in one call.

Plus it handles all the edge cases—SSR compatibility with proper hydration, automatic style restoration, multiple target support, proper cleanup on unmount in React development. No more janky layout shifts or broken scroll states.

This free open source React hook manages scroll state while you focus on building features. Whether you're creating React applications, Next.js interfaces, or TypeScript components, reliable scroll locking keeps your JavaScript development smooth.

Features

• Automatic locking with smart component mount detection and default behavior in React applications
• Manual control providing optional lock/unlock functions for dynamic scenarios in TypeScript components
• Width reflow prevention preventing layout shift by compensating for scrollbar width in Next.js projects
• Custom targets supporting scroll lock on specific elements or document body in JavaScript development
• Style restoration restoring original styles automatically when unlocking for React frameworks
• SSR compatible safely handling server-side rendering without hydration issues in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every scrolling scenario in React applications. CSS overflow controls handle basic scroll management perfectly. But when you need to prevent background scrolling without breaking your layout or causing visual jumps, this React hook delivers in Next.js projects.

Perfect for:

• Modal dialogs - Prevent background scrolling when overlays are active built with TypeScript
• Mobile navigation - Lock body scroll when slide-out menus are open using React patterns
• Lightbox galleries - Stop page scrolling during image/video viewing in JavaScript applications
• Form overlays - Prevent background interaction during multi-step processes in React components
• Loading screens - Lock scroll during full-screen loading states in Next.js applications
• Game interfaces - Prevent accidental scrolling during interactive gameplay using TypeScript safety

API Reference

useScrollLock

useScrollLock(options?: UseScrollLockOptions): UseScrollLockReturn

UseScrollLockOptions

UseScrollLockReturn

Common gotchas

Layout shift prevention requires calculation: The React hook measures scrollbar width and adds padding compensation to prevent content jumping when scrollbars hide in React applications. This calculation happens on mount and when locking, which may cause a brief delay on very slow devices.

Multiple components share scroll state: When multiple components use this React hook simultaneously, the last one to unlock restores the scroll state in TypeScript components. Plan your modal/overlay hierarchy carefully to avoid conflicts between nested or overlapping components.

Target elements must be scrollable: The hook only affects elements that actually have scrollbars in Next.js projects. Applying it to elements without overflow won't have any visible effect, but won't cause errors either.

SSR is handled automatically: The React hook safely does nothing on the server and activates after client hydration in JavaScript applications. No special configuration needed for Next.js or other SSR frameworks.

Scrollbar width varies by platform: Different operating systems have different scrollbar widths in React frameworks. The hook measures dynamically, but this can affect layout calculations on different devices.

Performance on slow devices: Scrollbar measurement and style application can be noticeable on very slow devices in TypeScript projects. Consider debouncing rapid lock/unlock operations for better performance.

Related hooks you will also like

Questions you might have