Registry / web-framework / react-remove-scroll

react-remove-scroll

library2.7.2jsnpmunverified

react-remove-scroll is a utility component for React applications that effectively disables scrolling outside of a specified child node. It provides robust scroll blocking for both mouse and touch devices, handles vertical and horizontal scrolling, and adeptly removes the document scrollbar while preserving layout space. Currently stable at version 2.7.2, the library maintains an active release cadence, frequently delivering bug fixes and minor features. Key differentiators include its support for nested scrollable elements, compatibility with React Portals, and a highly optimized bundle size, achieved with a significant 80% reduction in version 2.0.0. It also offers a sidecar pattern for lazy loading the scroll-blocking logic, allowing for further performance optimization.

web-framework

npm install react-remove-scroll

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-REMOVE-SCROL

react-remove-scroll

web-frameworkjavascriptv2.7.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RemoveScroll

✓ import { RemoveScroll } from 'react-remove-scroll';

✗ const RemoveScroll = require('react-remove-scroll').RemoveScroll;

Main component for basic usage. The library primarily uses ES Modules.

sidecar

✓ import { sidecar } from 'react-remove-scroll/sidecar';

✗ import { sidecar } from 'react-remove-scroll';

This specific named export is from a subpath for lazy loading patterns.

RemoveScroll (UI component)

✓ import { RemoveScroll } from 'react-remove-scroll/UI';

✗ import { RemoveScroll } from 'react-remove-scroll';

Used in conjunction with the `sidecar` pattern to import only the UI part initially.

RemoveScroll.classNames

✓ import { RemoveScroll } from 'react-remove-scroll'; // ... later ... <div className={RemoveScroll.classNames.fullWidth} />

Accesses predefined class names for handling fixed elements' widths when scroll is locked.

This example demonstrates how to use the RemoveScroll component to lock the body scroll while a modal-like element is open, allowing only the modal's content to be scrollable. A button toggles the scroll lock state.

import React, { useState } from 'react'; import { RemoveScroll } from 'react-remove-scroll'; function App() { const [isScrollLocked, setScrollLocked] = useState(false); return ( <div> <button onClick={() => setScrollLocked(!isScrollLocked)}> {isScrollLocked ? 'Unlock Scroll' : 'Lock Scroll'} </button> <p>Scrollable content outside the locked area.</p> <div style={{ height: '150vh', background: '#eee' }}> {Array(50).fill(0).map((_, i) => <p key={i}>Background content {i}</p>)} </div> {isScrollLocked && ( <div style={{ position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: '80%', height: '80%', background: 'white', border: '2px solid black', padding: '20px', zIndex: 1000, overflow: 'hidden' // Important for the modal itself }}> <RemoveScroll> <div style={{ height: '100%', overflowY: 'scroll', paddingRight: '15px' }}> <h2>Modal Content</h2> <p>This content is inside the RemoveScroll component. Only this area should be scrollable.</p> {Array(100).fill(0).map((_, i) => <p key={i}>Modal line {i}</p>)} </div> </RemoveScroll> </div> )} </div> ); } export default App;

Debug

Known issues

breakingVersion 2.0.0 introduced a breaking change requiring React 16.8 or newer. Applications using older React versions will encounter runtime errors.

fix

Upgrade your React and ReactDOM peer dependencies to version 16.8.0 or newer.

affects: >=2.0.0

gotchaUsing the `inert` prop on `RemoveScroll` will disable events for the *entire* rest of the page via `pointer-events`, which can interfere with React portals and lead to unexpected production issues. It's intended only for very specific, rare cases.

fix

Avoid using the `inert` prop unless absolutely necessary and thoroughly test its impact on event handling, especially with portals. Consider `noIsolation` for less aggressive event handling.

affects: >=2.0.0

gotchaThe `allowPinchZoom` prop is `false` by default, meaning pinch-to-zoom is prevented. Enabling it might break the 'scroll isolation' provided by the component.

fix

If pinch-to-zoom is required, set `allowPinchZoom={true}`, but be aware that it might compromise the complete scroll isolation effect. Test thoroughly on target devices.

affects: >=2.2.0

gotchaFor `position: fixed` elements on the page, their width might be affected when the scrollbar is removed. To ensure they maintain `width: 100%` or correct alignment, a special class name must be applied.

fix

Apply `RemoveScroll.classNames.fullWidth` to `position: fixed` elements that need their width adjusted. For elements needing `right: 0` adjustment, use `RemoveScroll.classNames.zeroRight`.

affects: >=2.0.0

gotchaThe library's internal `div` for event handling can be removed or customized. Not knowing this can lead to unnecessary wrapper divs or difficulty applying custom class names.

fix

If you need to pass props directly to a child or avoid an extra wrapper `div`, use the `forwardProps` prop on `RemoveScroll` and provide your own child element. Otherwise, use `className` directly on `RemoveScroll` for its internal div.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'useState') or similar errors related to hooks.

Using `react-remove-scroll` version 2.0.0 or higher with an older version of React (e.g., < 16.8).

fix

Upgrade your `react` and `react-dom` peer dependencies to version 16.8.0 or newer.

Scroll is still possible, or content shifts when scroll is locked.

Incorrect implementation (e.g., `RemoveScroll` not wrapping the correct content, or CSS conflicts) or unhandled edge cases like pinch-zoom.

fix

Ensure `RemoveScroll` is correctly wrapping the *only* intended scrollable content. Check if `allowPinchZoom` needs to be explicitly `false`. Inspect CSS for conflicting `overflow` properties or `position: fixed` elements not handled with `RemoveScroll.classNames`.

Events are blocked on elements outside the locked area, even when not using a modal.

Overuse or incorrect usage of the `inert` prop, which globally disables pointer events outside the locked area and its shards.

fix

Remove the `inert` prop from `RemoveScroll` unless absolutely necessary. For simpler event isolation, consider using `noIsolation` if event capturing is problematic with specific shadow DOM or third-party libraries.

My modal or overlay has the wrong width/position when scroll is locked.

Elements with `position: fixed` are not correctly adjusted when the scrollbar disappears, causing layout shifts.

fix

Apply `className={RemoveScroll.classNames.fullWidth}` to any `position: fixed` elements (like modals or headers) that are expected to span 100% width, to ensure they maintain correct sizing when the scrollbar is hidden.

Upgrade

Version history

2.7.2latest on npm

Audit

Dependencies

@types/reactoptionalTypeScript type definitions for React components.

reactrequiredCore React library; required as a peer dependency for component functionality.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/theKashey/react-remove-scroll ↗

packagehttps://www.npmjs.com/package/react-remove-scroll ↗