React Perfect Scrollbar

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

  cause Incorrect import of the `PerfectScrollbar` component, often due to using `require()` or incorrect named vs. default import.
  fix Use `import PerfectScrollbar from 'react-perfect-scrollbar';` to correctly import the default export.

• Scrollbar not visible or not updating when content changes.

  cause The underlying perfect-scrollbar instance needs to be told to recalculate its dimensions after content changes.
  fix Obtain a ref to the `PerfectScrollbar` component and call `ref.current.updateScroll()` after content changes, or implement custom sync logic using the `onSync` prop.

• Warning: Received `option` as a prop on `PerfectScrollbar`. This is not supported. If you meant to pass this to the underlying perfect-scrollbar instance, use the `options` prop instead.

  cause Using the deprecated `option` prop instead of `options` for perfect-scrollbar configuration.
  fix Rename the prop from `option` to `options`.

• Module not found: Can't resolve 'react-perfect-scrollbar/dist/css/styles.css' in '...' or Styles appear broken/missing.

  cause The CSS file for `perfect-scrollbar` is not being imported or processed by the build system.
  fix Add `import 'react-perfect-scrollbar/dist/css/styles.css';` to your main application file (e.g., `App.js` or `index.js`). Verify your bundler (e.g., Webpack, Vite) has a loader configured for CSS files.

Warnings

• breaking The `option` prop for perfect-scrollbar initialization parameters was deprecated and renamed to `options`. While `option` might still work if `options` is not provided, it's advised to update to `options` for future compatibility.
  Fix: Rename the prop from `option={...}` to `options={...}`.
• breaking The underlying `perfect-scrollbar` library was updated to version 1.4.0, which introduced certain behavior changes. Developers should review the `perfect-scrollbar` release notes for version 1.4.0 to understand any potential impact on custom configurations or expected scroll behavior.
  Fix: Consult the `perfect-scrollbar` v1.4.0 release notes for specific behavior changes and adjust component usage or options accordingly.
• gotcha When the content within PerfectScrollbar changes dynamically (e.g., via AJAX, state updates), the scrollbar might not automatically recalculate its size and position, leading to incorrect scrollbar appearance or functionality.
  Fix: Manually call the `updateScroll()` method via a ref to the PerfectScrollbar component, or use the `onSync` prop to customize/debounce the internal `ps.update()` calls for better performance in rapidly changing content scenarios.
• gotcha Omitting the import of the required CSS file (`react-perfect-scrollbar/dist/css/styles.css`) will result in unstyled or non-functional scrollbars, as the component relies on these styles for its visual presentation.
  Fix: Ensure `import 'react-perfect-scrollbar/dist/css/styles.css';` is included in your application's entry point or a relevant component file, and that your build tool is configured to process CSS imports.

Install

• npm install react-perfect-scrollbar npm
• yarn add react-perfect-scrollbar yarn
• pnpm add react-perfect-scrollbar pnpm

Imports

• PerfectScrollbar
  wrong:

  const PerfectScrollbar = require('react-perfect-scrollbar');

  correct:

  import PerfectScrollbar from 'react-perfect-scrollbar';

  CommonJS `require` is not the idiomatic way to import this ESM-first library in modern React projects. Use default import for the component.
• CSS Styles
  wrong:

  require('react-perfect-scrollbar/dist/css/styles.css');

  correct:

  import 'react-perfect-scrollbar/dist/css/styles.css';

  The CSS must be imported separately. Ensure your build system (e.g., Webpack) is configured to handle CSS imports.
• PerfectScrollbarProps
  wrong:

  import { PerfectScrollbarProps } from 'react-perfect-scrollbar';

  correct:

  import type { PerfectScrollbarProps } from 'react-perfect-scrollbar';

  Import types using `import type` for better type safety and bundle optimization in TypeScript projects.

Quickstart

Demonstrates basic usage of PerfectScrollbar, including importing the component and its styles, wrapping content, configuring options, accessing the containerRef, and handling scroll events in a functional React component.

import React, { useRef, useEffect } from 'react';
import PerfectScrollbar from 'react-perfect-scrollbar';
import 'react-perfect-scrollbar/dist/css/styles.css';

function MyScrollableComponent() {
  const scrollRef = useRef(null);

  useEffect(() => {
    // Example: Scroll to bottom on mount
    if (scrollRef.current) {
      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
    }
  }, []);

  return (
    <div style={{ width: '300px', height: '200px', border: '1px solid #ccc' }}>
      <PerfectScrollbar
        containerRef={ref => (scrollRef.current = ref)}
        options={{ suppressScrollX: false }}
        onScrollY={container => console.log(`Scrolled Y: ${container.scrollTop}`)}
        style={{ maxHeight: '100%', maxWidth: '100%' }}
      >
        <div style={{ height: '500px', padding: '10px' }}>
          {Array.from({ length: 50 }).map((_, i) => (
            <p key={i}>Item {i + 1}: This is some scrollable content.</p>
          ))}
        </div>
      </PerfectScrollbar>
    </div>
  );
}

// To render this:
// ReactDOM.render(<MyScrollableComponent />, document.getElementById('root'));