useScrollLock

React hook that locks and unlocks scroll on target elements with width reflow prevention and automatic cleanup.

Loading component...

"use client"import { useState, useRef } from "react"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 scrollRef = useRef<HTMLDivElement>(null)    const { isLocked, lock, unlock } = useScrollLock({    autoLock: false,    lockTarget: "#scrollable-content",  })  return (    <div className="space-y-3 p-4 max-w-sm mx-auto">      <div className="space-y-2">        <div className="flex items-center justify-between">          <Label className="text-sm font-medium">Scroll Lock Control</Label>          <Badge             variant={isLocked ? "destructive" : "secondary"}             className="text-xs"          >            {isLocked ? "🔒 Locked" : "🔓 Unlocked"}          </Badge>        </div>      </div>      <div className="space-y-2">        <Label className="text-sm font-medium">Scrollable Content Area</Label>        <div          id="scrollable-content"          ref={scrollRef}          className="h-64 overflow-y-auto border-2 rounded-lg p-3 bg-background"        >          <div className="space-y-3">            {Array.from({ length: 25 }, (_, i) => (              <div key={i} className="p-3 rounded-lg bg-white dark:bg-gray-900 border shadow-sm">                <div className="flex items-center gap-2 mb-2">                  <span className="text-lg">📄</span>                  <span className="font-medium text-sm">Article {i + 1}</span>                  <Badge variant="outline" className="text-xs ml-auto">                    {isLocked ? "🚫" : "📜"}                  </Badge>                </div>                <div className="text-xs text-muted-foreground">                  {isLocked                     ? "Scroll functionality is currently disabled by the lock mechanism."                    : "This content area is scrollable. Try the lock button to disable scrolling."                  }                </div>                <div className="text-xs text-muted-foreground mt-2 leading-relaxed">                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.                </div>              </div>            ))}          </div>        </div>        <div className="text-xs text-center text-muted-foreground">          {isLocked             ? "⚠️ Scrolling is locked - content is not scrollable"             : "💡 Try scrolling above, then click 'Lock' to disable it"          }        </div>      </div>      <div className="grid grid-cols-3 gap-1">        <Button          onClick={lock}          disabled={isLocked}          variant="destructive"          size="sm"          className="h-8 text-xs"        >          Lock        </Button>        <Button          onClick={unlock}          disabled={!isLocked}          variant="default"          size="sm"          className="h-8 text-xs bg-green-600 hover:bg-green-700"        >          Unlock        </Button>        <Button          onClick={() => setShowModal(true)}          variant="outline"          size="sm"          className="h-8 text-xs"        >          Modal        </Button>      </div>      <div className="text-xs text-muted-foreground text-center">        Lock prevents scrolling in the target area      </div>      {showModal && <Modal onClose={() => setShowModal(false)} />}    </div>  )}function Modal({ onClose }: { onClose: () => void }) {  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-4 max-w-sm w-full shadow-lg">        <div className="flex items-center justify-between mb-3">          <h2 className="font-semibold">Body Scroll Lock</h2>          <Badge variant="destructive" className="text-xs">            🔒 Active          </Badge>        </div>        <p className="text-sm text-muted-foreground mb-4">          The page scroll is automatically locked while this modal is open. Try scrolling the background.        </p>        <Button           onClick={onClose}          className="w-full h-8 text-xs"        >          Close Modal        </Button>      </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 }

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

Features

Automatic locking - Locks scroll when component mounts by default
Manual control - Optional manual lock/unlock functions
Width reflow prevention - Prevents layout shift by compensating for scrollbar width
Custom targets - Lock scroll on specific elements or body
Style restoration - Restores original styles when unlocking
SSR compatible - Safely handles server-side rendering
Cleanup on unmount - Automatically unlocks scroll when component unmounts

Usage

import { useScrollLock } from "@/hooks/use-scroll-lock"

// Auto-lock on mount (perfect for modals)
function Modal() {
  useScrollLock()
  return <div>Modal content</div>
}

// Manual control
function App() {
  const { isLocked, lock, unlock } = useScrollLock({ autoLock: false })
  
  return (
    <div>
      <button onClick={lock}>Lock Scroll</button>
      <button onClick={unlock}>Unlock Scroll</button>
      <p>Status: {isLocked ? "Locked" : "Unlocked"}</p>
    </div>
  )
}

API Reference

useScrollLock(options?: UseScrollLockOptions): UseScrollLockReturn

UseScrollLockOptions

Property	Type	Default	Description
`autoLock`	`boolean`	`true`	Whether to lock scroll automatically on mount
`lockTarget`	`HTMLElement \| string`	`document.body`	Target element to lock (element or CSS selector)
`widthReflow`	`boolean`	`true`	Whether to prevent width reflow by adding padding

UseScrollLockReturn

Property	Type	Description
`isLocked`	`boolean`	Current lock state
`lock`	`() => void`	Function to lock scroll
`unlock`	`() => void`	Function to unlock scroll

Usage Examples

function Modal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
  // Automatically locks body scroll when modal is open
  useScrollLock()

  if (!isOpen) return null

  return (
    <div className="modal-overlay">
      <div className="modal">
        <h2>Modal Title</h2>
        <p>Body scroll is locked while this modal is open</p>
        <button onClick={onClose}>Close</button>
      </div>
    </div>
  )
}

Manual Control

function ScrollableContent() {
  const { isLocked, lock, unlock } = useScrollLock({
    autoLock: false,
    lockTarget: "#scrollable-area"
  })

  return (
    <div>
      <div id="scrollable-area" style={{ height: 200, overflow: "auto" }}>
        {/* Long content */}
      </div>
      
      <button onClick={isLocked ? unlock : lock}>
        {isLocked ? "Unlock" : "Lock"} Scroll
      </button>
    </div>
  )
}

Custom Target Element

function CustomScrollLock() {
  const scrollRef = useRef<HTMLDivElement>(null)
  
  const { isLocked, lock, unlock } = useScrollLock({
    autoLock: false,
    lockTarget: scrollRef.current,
    widthReflow: false // Disable width reflow for custom elements
  })

  return (
    <div>
      <div ref={scrollRef} className="custom-scroll-area">
        Content
      </div>
      <button onClick={lock}>Lock Custom Area</button>
    </div>
  )
}

Sidebar/Drawer

function Sidebar({ isOpen }: { isOpen: boolean }) {
  useScrollLock({ autoLock: isOpen })

  return (
    <div className={`sidebar ${isOpen ? "open" : "closed"}`}>
      <p>Sidebar content</p>
      <p>Body scroll locked when sidebar is open</p>
    </div>
  )
}

Full-Screen Loading

function FullScreenLoader({ isLoading }: { isLoading: boolean }) {
  useScrollLock({ autoLock: isLoading })

  if (!isLoading) return null

  return (
    <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
      <div className="spinner">Loading...</div>
    </div>
  )
}

Photo Gallery

function PhotoGallery() {
  const [selectedPhoto, setSelectedPhoto] = useState<string | null>(null)
  
  // Lock scroll when photo is selected
  useScrollLock({ autoLock: !!selectedPhoto })

  return (
    <div>
      <div className="photo-grid">
        {photos.map(photo => (
          <img 
            key={photo.id}
            onClick={() => setSelectedPhoto(photo.src)}
            src={photo.thumbnail}
            alt={photo.alt}
          />
        ))}
      </div>
      
      {selectedPhoto && (
        <div className="photo-lightbox" onClick={() => setSelectedPhoto(null)}>
          <img src={selectedPhoto} alt="Full size" />
        </div>
      )}
    </div>
  )
}

Conditional Locking

function ConditionalLock() {
  const [shouldLock, setShouldLock] = useState(false)
  const isMobile = useMediaQuery("(max-width: 768px)")
  
  // Only lock scroll on mobile devices
  useScrollLock({ 
    autoLock: shouldLock && isMobile,
    widthReflow: !isMobile // Only prevent reflow on desktop
  })

  return (
    <div>
      <button onClick={() => setShouldLock(!shouldLock)}>
        Toggle Lock {isMobile ? "(Mobile)" : "(Desktop)"}
      </button>
    </div>
  )
}

Common Use Cases

Modal dialogs - Prevent background scrolling when modal is open
Sidebar/drawer navigation - Lock body scroll when side panel is active
Full-screen overlays - Loading screens, image lightboxes
Form wizards - Multi-step forms that shouldn't allow background interaction
Video players - Full-screen video modes
Game interfaces - Prevent accidental scrolling during gameplay
Mobile menus - Prevent body scroll when mobile menu is open
Infinite scroll pausing - Temporarily disable scroll during data loading

Implementation Details

Uses overflow: hidden to lock scroll
Calculates scrollbar width and adds equivalent padding to prevent layout shift
Stores original styles in refs for proper restoration
Uses useIsomorphicLayoutEffect to avoid SSR issues
Automatically unlocks scroll when component unmounts
Supports both CSS selectors and direct element references
Handles edge cases like missing target elements gracefully

Width Reflow Prevention

When widthReflow is enabled (default):

Calculates the scrollbar width by comparing offsetWidth and scrollWidth
Adds padding-right to compensate for the hidden scrollbar
Uses window.innerWidth for body element to account for global scrollbar
Preserves existing padding-right values by adding to them

Best Practices

Use auto-lock for modals: Set autoLock: true for modal components
Manual control for toggles: Use manual control for toggleable content
Disable reflow for custom elements: Set widthReflow: false for non-body targets
Handle mobile separately: Consider different behavior on mobile devices
Test with existing padding: Ensure the hook works with elements that already have padding
Clean up properly: The hook automatically cleans up, but be mindful of component lifecycles

useScrollLock

Reactuse-scroll-lock

Reactbutton

Reactbadge

Reactlabel

On this page