{"id":11509,"library":"overlayscrollbars-react","title":"OverlayScrollbars for React","description":"OverlayScrollbars-react is the official React wrapper for the highly customizable OverlayScrollbars library, providing native-like scrollbar functionality with enhanced styling capabilities and flexible configuration. The current stable version, 0.5.6, is built to be compatible with OverlayScrollbars v2.x. It offers both a component-based approach via `OverlayScrollbarsComponent` and a hook-based API with `useOverlayScrollbars`, catering to different integration preferences within React applications. Releases are frequent, often mirroring updates and feature additions in the core OverlayScrollbars library, ensuring an actively maintained and up-to-date solution. Key differentiators include its robust performance, comprehensive accessibility features (especially in scenarios where native scrollbars are problematic), and a focus on deferred initialization to optimize application load times and user experience.","status":"active","version":"0.5.6","language":"javascript","source_language":"en","source_url":"https://github.com/KingSora/OverlayScrollbars","tags":["javascript","overlayscrollbars","react","component","hook","hooks","styleable","custom","scrollbar","typescript"],"install":[{"cmd":"npm install overlayscrollbars-react","lang":"bash","label":"npm"},{"cmd":"yarn add overlayscrollbars-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add overlayscrollbars-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required React runtime for component and hook functionality.","package":"react","optional":false},{"reason":"The core JavaScript library providing the scrollbar functionality.","package":"overlayscrollbars","optional":false}],"imports":[{"note":"This package is primarily designed for ESM; CommonJS `require` syntax is not recommended and may cause issues.","wrong":"const OverlayScrollbarsComponent = require('overlayscrollbars-react').OverlayScrollbarsComponent;","symbol":"OverlayScrollbarsComponent","correct":"import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';"},{"note":"The hook is a named export from the main package, not a default export from a sub-path.","wrong":"import useOverlayScrollbars from 'overlayscrollbars-react/hook';","symbol":"useOverlayScrollbars","correct":"import { useOverlayScrollbars } from 'overlayscrollbars-react';"},{"note":"The CSS file must be imported directly from the core `overlayscrollbars` package, not the React wrapper.","wrong":"import 'overlayscrollbars-react/overlayscrollbars.css';","symbol":"CSS Styles","correct":"import 'overlayscrollbars/overlayscrollbars.css';"}],"quickstart":{"code":"import { useRef } from 'react';\nimport { OverlayScrollbarsComponent } from 'overlayscrollbars-react';\nimport 'overlayscrollbars/overlayscrollbars.css';\n\nfunction MyScrollableContent() {\n  const scrollRef = useRef(null);\n\n  const handleScroll = (instance, event) => {\n    console.log('Scroll event!', instance.state().scrollOffsetElement.scrollTop);\n  };\n\n  return (\n    <OverlayScrollbarsComponent\n      element=\"div\"\n      options={{\n        scrollbars: { autoHide: 'scroll', theme: 'os-theme-dark' },\n        overflow: { x: 'hidden', y: 'scroll' }\n      }}\n      events={{ scroll: handleScroll }}\n      defer\n      style={{ maxHeight: '200px', width: '300px', border: '1px solid #ccc' }}\n      ref={scrollRef}\n    >\n      <div style={{ padding: '15px', height: '500px' }}>\n        <p>This is a long piece of content that will require scrolling.</p>\n        <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>\n        <p>More content to ensure the scrollbar appears. Keep scrolling!</p>\n      </div>\n    </OverlayScrollbarsComponent>\n  );\n}\n\nexport default MyScrollableContent;","lang":"typescript","description":"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."},"warnings":[{"fix":"Always add the `defer` boolean prop to your `OverlayScrollbarsComponent` usage: `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.","message":"It 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update `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 } }`).","message":"The `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.","severity":"breaking","affected_versions":">=2.13.0 (core OverlayScrollbars)"},{"fix":"Ensure you import `'overlayscrollbars/overlayscrollbars.css'`. If that path fails, try `'overlayscrollbars/styles/overlayscrollbars.css'`.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review 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.","message":"This 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.","severity":"breaking","affected_versions":"<2.0.0 (core OverlayScrollbars)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `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';`.","cause":"The CSS file for the core OverlayScrollbars library is not being imported correctly or at all.","error":"Module not found: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' OR Cannot find module 'overlayscrollbars/overlayscrollbars.css'"},{"fix":"Ensure you have `overlayscrollbars` installed (`npm install overlayscrollbars` or `yarn add overlayscrollbars`) and that `react` meets the peer dependency `'>=16.8.0'`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'scrollbars') OR 'OverlayScrollbars' is not defined"},{"fix":"Ensure `useOverlayScrollbars` is called directly at the top level of your functional component or within a custom hook, adhering to React's Rules of Hooks.","cause":"Attempting to call `useOverlayScrollbars` outside of a functional React component or another custom hook.","error":"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."}],"ecosystem":"npm"}