React Custom Scrollbars Component (Fork)

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.

  cause Incorrect import of `Scrollbars` component, often due to a default import instead of a named import.
  fix Change `import Scrollbars from 'react-custom-scrollbars-2';` to `import { Scrollbars } from 'react-custom-scrollbars-2';`

• TypeError: Cannot read properties of undefined (reading 'current')

  cause Often occurs when trying to access `this.refs.scrollbars.getScrollHeight()` or similar methods, indicating `this.refs` is not properly set up or the component is not yet mounted.
  fix Ensure the component is fully mounted before attempting to access its instance methods. For functional components, use `useRef` and ensure the ref is attached to the `Scrollbars` component and has been assigned.

• Scrollbars are not appearing or styled correctly despite applying custom render props.

  cause Commonly, the custom `renderView`, `renderTrack`, or `renderThumb` components do not correctly apply the style and props provided to them by the `Scrollbars` component.
  fix Ensure your custom render functions correctly spread `props` (e.g., `<div {...props} />`) and apply `style` when provided, as these are crucial for positioning and visibility.

Warnings

• gotcha This package is a fork of the original `react-custom-scrollbars`. While it aims for bug fixes and active maintenance, be aware of the lineage when migrating from the original package, as specific behavioral changes or new bugs might exist that differ from the original's last stable release.
  Fix: Review the GitHub repository's issues and changelog for specific differences or migration notes if coming from the original `react-custom-scrollbars`.
• gotcha When using `autoHeight`, ensure `autoHeightMin` and `autoHeightMax` are set appropriately to prevent layout shifts or incorrect sizing, especially if the content height can vary wildly. Default values might not always suit your specific use case.
  Fix: Explicitly define `autoHeightMin` and `autoHeightMax` props to control the scrollable area's boundaries based on your design requirements.
• gotcha Custom rendering components (`renderView`, `renderThumbHorizontal`, etc.) must pass `ref` to their children if they internally use `ref` to manage scrollbar elements. Failure to do so can break internal calculations or event handling.
  Fix: Ensure your custom render functions correctly forward `ref` props received from `Scrollbars` to the underlying DOM elements or React components that need them.

Install

• npm install react-custom-scrollbars-2 npm
• yarn add react-custom-scrollbars-2 yarn
• pnpm add react-custom-scrollbars-2 pnpm

Imports

• Scrollbars
  wrong:

  const { Scrollbars } = require('react-custom-scrollbars-2');

  correct:

  import { Scrollbars } from 'react-custom-scrollbars-2';

  The library primarily uses named exports. CommonJS `require` works but ESM `import` is the recommended modern approach and supported by TypeScript.
• ScrollbarProps

  import type { ScrollbarProps } from 'react-custom-scrollbars-2';

  When using TypeScript, import `ScrollbarProps` for type annotations on component props or direct manipulation.
• Scrollbars (as default)
  wrong:

  import Scrollbars from 'react-custom-scrollbars-2';

  correct:

  import Scrollbars from 'react-custom-scrollbars-2/lib/Scrollbars';

  While the main export is named, some bundlers or older setups might interpret `import Scrollbars from 'pkg'` as a default import. Always use named `import { Scrollbars }` from the root for clarity and consistency. The default export might be from a specific path.

Quickstart

This quickstart demonstrates rendering a `Scrollbars` component with basic styling, auto-hide functionality, and overflowing content.

import React, { Component } from 'react';
import { Scrollbars } from 'react-custom-scrollbars-2';

class App extends Component {
  render() {
    return (
      <div style={{ padding: '20px', border: '1px solid #ccc', maxWidth: '600px', margin: '50px auto' }}>
        <h1>My Content with Custom Scrollbars</h1>
        <Scrollbars 
          style={{ width: 500, height: 300, border: '1px solid #eee' }}
          autoHide
          autoHideTimeout={1000}
          autoHideDuration={200}
        >
          <p>Some great content that will overflow the container. This paragraph and subsequent content are here to demonstrate the scrolling functionality. </p>
          <p>You can customize the appearance and behavior of the scrollbars, such as making them automatically hide when not in use. This helps maintain a clean UI.</p>
          <p>More content to fill the space and ensure scrolling is necessary. Keep adding text until the scrollbar appears, allowing you to test the component effectively.</p>
          <p>Final paragraph for testing purposes. Enjoy your custom scrollbars!</p>
          <p>This is even more content to make sure the scrollbar is definitely there.</p>
          <p>And one last line.</p>
        </Scrollbars>
      </div>
    );
  }
}

// For a real app, you would render this component:
// ReactDOM.render(<App />, document.getElementById('root'));
export default App;