Registry /
web-framework / overlayscrollbars-react
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OverlayScrollbarsComponent
✓ import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';
✗ const OverlayScrollbarsComponent = require('overlayscrollbars-react').OverlayScrollbarsComponent;
This package is primarily designed for ESM; CommonJS `require` syntax is not recommended and may cause issues.
useOverlayScrollbars
✓ import { useOverlayScrollbars } from 'overlayscrollbars-react';
✗ import useOverlayScrollbars from 'overlayscrollbars-react/hook';
The hook is a named export from the main package, not a default export from a sub-path.
CSS Styles
✓ import 'overlayscrollbars/overlayscrollbars.css';
✗ import 'overlayscrollbars-react/overlayscrollbars.css';
The CSS file must be imported directly from the core `overlayscrollbars` package, not the React wrapper.
This quickstart demonstrates how to integrate OverlayScrollbars into a React component using `OverlayScrollbarsComponent`, apply custom options, handle scroll events, and ensure performance with deferred initialization.
import { useRef } from 'react';
import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';
import 'overlayscrollbars/overlayscrollbars.css';
function MyScrollableContent() {
const scrollRef = useRef(null);
const handleScroll = (instance, event) => {
console.log('Scroll event!', instance.state().scrollOffsetElement.scrollTop);
};
return (
<OverlayScrollbarsComponent
element="div"
options={{
scrollbars: { autoHide: 'scroll', theme: 'os-theme-dark' },
overflow: { x: 'hidden', y: 'scroll' }
}}
events={{ scroll: handleScroll }}
defer
style={{ maxHeight: '200px', width: '300px', border: '1px solid #ccc' }}
ref={scrollRef}
>
<div style={{ padding: '15px', height: '500px' }}>
<p>This is a long piece of content that will require scrolling.</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
<p>More content to ensure the scrollbar appears. Keep scrolling!</p>
</div>
</OverlayScrollbarsComponent>
);
}
export default MyScrollableContent;
Debug
Known issues
gotchaIt is highly recommended to use the `defer` prop on `OverlayScrollbarsComponent` to defer initialization to a browser's idle period, improving initial load performance and user experience.fixAlways add the `defer` boolean prop to your `OverlayScrollbarsComponent` usage: `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.
affects: >=0.1.0
breakingThe `options.debounce` property in OverlayScrollbars (which directly affects the `options` prop of the React wrapper) has been deprecated in its old syntax. While still supported, it's advised to use the new object-based syntax for more fine-grained control.fixUpdate `options.debounce` from a single number (e.g., `{ debounce: 50 }`) to an object specifying debounce values for `mutations`, `resizes`, `events`, and `environmental changes` (e.g., `{ debounce: { mutations: 50, resizes: 100 } }`). affects: >=2.13.0 (core OverlayScrollbars)
gotchaThe primary CSS file for OverlayScrollbars should be imported from the core `overlayscrollbars` package, not `overlayscrollbars-react`. There might also be two possible paths for the CSS.fixEnsure you import `'overlayscrollbars/overlayscrollbars.css'`. If that path fails, try `'overlayscrollbars/styles/overlayscrollbars.css'`.
affects: >=0.1.0
breakingThis React wrapper relies on OverlayScrollbars v2.x. If you are migrating from an older setup that used OverlayScrollbars v1.x, be aware that v2.x was a complete rewrite with significant API, option, and CSS breaking changes in the core library.fixReview the official OverlayScrollbars v1 to v2 migration guide. All components and hooks in `overlayscrollbars-react` are designed for v2 and will not work with v1 of the core library.
affects: <2.0.0 (core OverlayScrollbars)
Errors
Common errors & fixes
Module not found: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' OR Cannot find module 'overlayscrollbars/overlayscrollbars.css'
The CSS file for the core OverlayScrollbars library is not being imported correctly or at all.
fixAdd `import 'overlayscrollbars/overlayscrollbars.css';` to your main application file or the component where OverlayScrollbars is used. If this path doesn't work, try `import 'overlayscrollbars/styles/overlayscrollbars.css';`.
TypeError: Cannot read properties of undefined (reading 'scrollbars') OR 'OverlayScrollbars' is not defined
The `overlayscrollbars` peer dependency is either not installed, or its initialization is failing, leading to an undefined instance when the React wrapper tries to use it.
fixEnsure you have `overlayscrollbars` installed (`npm install overlayscrollbars` or `yarn add overlayscrollbars`) and that `react` meets the peer dependency `'>=16.8.0'`.
React Hook 'useOverlayScrollbars' cannot be called inside a callback. React Hooks must be called in a React function component or a custom React Hook function.
Attempting to call `useOverlayScrollbars` outside of a functional React component or another custom hook.
fixEnsure `useOverlayScrollbars` is called directly at the top level of your functional component or within a custom hook, adhering to React's Rules of Hooks.
Audit
Dependencies
reactrequiredRequired React runtime for component and hook functionality.
overlayscrollbarsrequiredThe core JavaScript library providing the scrollbar functionality.