@custom-react-hooks/use-lock-body-scroll
v1.5.1
Published
`useLockBodyScroll` is a React hook for controlling the scroll behavior of the body element in web applications. It's particularly useful for scenarios like opening modals or overlays where background scroll needs to be disabled.
Downloads
1,905
Readme
useLockBodyScroll Hook
useLockBodyScroll
is a React hook for controlling the scroll behavior of the body element in web applications. It's particularly useful for scenarios like opening modals or overlays where background scroll needs to be disabled.
Features
- Conditional Scroll Lock: Allows you to conditionally enable or disable the body scroll.
- Style Preservation: Preserves the original body overflow style and restores it upon unmounting.
- Server-Side Rendering (SSR) Compatibility: Safe for use in SSR environments by checking for the
document
object. - Synchronous Execution: Uses
useLayoutEffect
for synchronous updates to the DOM.
Installation
Installing Only Current Hooks
npm install @custom-react-hooks/use-lock-body-scroll
or
yarn add @custom-react-hooks/use-lock-body-scroll
Installing All Hooks
npm install @custom-react-hooks/all
or
yarn add @custom-react-hooks/all
Importing the Hook
The useLockBodyScroll
hook must be imported using a named import as shown below:
Named Import:
import { useLockBodyScroll } from '@custom-react-hooks/use-lock-body';
This approach ensures that the hook integrates seamlessly into your project, maintaining consistency and predictability in how you use our package.
Usage
import React, { useState } from 'react';
import { useLockBodyScroll } from '@custom-react-hooks/all';
const LockBodyScrollComponent= () => {
const [isModalOpen, setIsModalOpen] = useState(false);
useLockBodyScroll(isModalOpen);
return (
<div>
<p>{isModalOpen ? 'Scroll hidden' : 'When you click on the button scroll will be hidden'}</p>
<button onClick={() => setIsModalOpen(true)}>Open Modal</button>
{isModalOpen && (
<div className="modal">
<div>
<p>Modal Content</p>
<button onClick={() => setIsModalOpen(false)}>Close Modal</button>
</div>
</div>
)}
</div>
);
};
export default LockBodyScrollComponent;
In this example, the hook is used to lock the body scroll when the modal is open.
API Reference
lock
: A boolean indicating whether to lock (true
) or unlock (false
) the body scroll.
Use Cases
Modals and Popups: This is the most common use case. When a modal or popup is opened, it's often desirable to lock the background content to prevent the user from scrolling. This keeps the focus on the modal content.
Full-Screen Menus: In mobile-responsive designs or certain desktop layouts, when a full-screen menu is opened, you might want to lock the scroll to keep the user's focus on the navigation options.
Onboarding Flows or Guided Tours: If your application has a step-by-step onboarding process or a guided tour, you might want to lock scrolling to ensure the user follows the flow without distractions.
Image or Video Galleries: When a user clicks on an image or video to view it in a larger format (like a lightbox), locking the scroll can enhance the viewing experience by removing background distractions.
Infinite Scroll Prevention: In some scenarios, you might want to temporarily disable infinite scrolling features. For example, when a user performs an action that requires attention or confirmation, you could lock the scroll to keep them focused on the task.
Interactive Games or Quizzes: If you're embedding games or quizzes in your web application, you might want to lock the background scroll when these elements are in focus to enhance user engagement and prevent accidental scroll-offs.
Alerts or Critical Notifications: When displaying critical alerts or notifications that require immediate attention or action, disabling the background scroll can ensure that the user addresses these alerts without distraction.
Complex Forms or Surveys: In a long, multi-step form or survey, you may want to lock the scroll when displaying validation errors or important information to ensure the user sees and acknowledges these messages.
Contributing
Your contributions to improve useLockBodyScroll
are welcome. Feel free to submit issues or pull requests to the repository.