OverlayScrollbars for React

Common errors

• Module not found: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' OR Cannot find module 'overlayscrollbars/overlayscrollbars.css'

  cause The CSS file for the core OverlayScrollbars library is not being imported correctly or at all.
  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';`.

• TypeError: Cannot read properties of undefined (reading 'scrollbars') OR 'OverlayScrollbars' is not defined

  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.
  fix Ensure 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.

  cause Attempting to call `useOverlayScrollbars` outside of a functional React component or another custom hook.
  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.

Warnings

• gotcha 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.
  Fix: Always add the `defer` boolean prop to your `OverlayScrollbarsComponent` usage: `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.
• breaking 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.
  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 } }`).
• gotcha 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.
  Fix: Ensure you import `'overlayscrollbars/overlayscrollbars.css'`. If that path fails, try `'overlayscrollbars/styles/overlayscrollbars.css'`.
• breaking 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.
  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.

Install

• npm install overlayscrollbars-react npm
• yarn add overlayscrollbars-react yarn
• pnpm add overlayscrollbars-react pnpm

Imports

• OverlayScrollbarsComponent
  wrong:

  const OverlayScrollbarsComponent = require('overlayscrollbars-react').OverlayScrollbarsComponent;

  correct:

  import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';

  This package is primarily designed for ESM; CommonJS `require` syntax is not recommended and may cause issues.
• useOverlayScrollbars
  wrong:

  import useOverlayScrollbars from 'overlayscrollbars-react/hook';

  correct:

  import { useOverlayScrollbars } from 'overlayscrollbars-react';

  The hook is a named export from the main package, not a default export from a sub-path.
• CSS Styles
  wrong:

  import 'overlayscrollbars-react/overlayscrollbars.css';

  correct:

  import 'overlayscrollbars/overlayscrollbars.css';

  The CSS file must be imported directly from the core `overlayscrollbars` package, not the React wrapper.

Quickstart

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;