{"id":11823,"library":"react-perfect-scrollbar","title":"React Perfect Scrollbar","description":"react-perfect-scrollbar is a React component that wraps the 'perfect-scrollbar' library, providing a highly customizable and performant scrollbar solution for web applications. The current stable version is 1.5.8. Releases appear to be less frequent than monthly, but consistent enough to indicate active maintenance, with recent updates addressing bug fixes, new features like `onSync`, and improved TypeScript definitions. Its primary differentiator is offering a polished, native-feeling scroll experience that avoids the limitations and inconsistencies of default browser scrollbars, especially useful in complex UIs where standard scrollbars might be visually jarring or functionally inadequate. It achieves this by taking control of scroll behavior and rendering custom scrollbars that blend seamlessly with application design, while still relying on the underlying perfect-scrollbar library for the core functionality.","status":"active","version":"1.5.8","language":"javascript","source_language":"en","source_url":"https://github.com/goldenyz/react-perfect-scrollbar","tags":["javascript","react","scrollbar","perfect-scrollbar","react-scrollbar","typescript"],"install":[{"cmd":"npm install react-perfect-scrollbar","lang":"bash","label":"npm"},{"cmd":"yarn add react-perfect-scrollbar","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-perfect-scrollbar","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency for React applications.","package":"react-dom","optional":false},{"reason":"Core underlying scrollbar library.","package":"perfect-scrollbar","optional":false}],"imports":[{"note":"CommonJS `require` is not the idiomatic way to import this ESM-first library in modern React projects. Use default import for the component.","wrong":"const PerfectScrollbar = require('react-perfect-scrollbar');","symbol":"PerfectScrollbar","correct":"import PerfectScrollbar from 'react-perfect-scrollbar';"},{"note":"The CSS must be imported separately. Ensure your build system (e.g., Webpack) is configured to handle CSS imports.","wrong":"require('react-perfect-scrollbar/dist/css/styles.css');","symbol":"CSS Styles","correct":"import 'react-perfect-scrollbar/dist/css/styles.css';"},{"note":"Import types using `import type` for better type safety and bundle optimization in TypeScript projects.","wrong":"import { PerfectScrollbarProps } from 'react-perfect-scrollbar';","symbol":"PerfectScrollbarProps","correct":"import type { PerfectScrollbarProps } from 'react-perfect-scrollbar';"}],"quickstart":{"code":"import React, { useRef, useEffect } from 'react';\nimport PerfectScrollbar from 'react-perfect-scrollbar';\nimport 'react-perfect-scrollbar/dist/css/styles.css';\n\nfunction MyScrollableComponent() {\n  const scrollRef = useRef(null);\n\n  useEffect(() => {\n    // Example: Scroll to bottom on mount\n    if (scrollRef.current) {\n      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;\n    }\n  }, []);\n\n  return (\n    <div style={{ width: '300px', height: '200px', border: '1px solid #ccc' }}>\n      <PerfectScrollbar\n        containerRef={ref => (scrollRef.current = ref)}\n        options={{ suppressScrollX: false }}\n        onScrollY={container => console.log(`Scrolled Y: ${container.scrollTop}`)}\n        style={{ maxHeight: '100%', maxWidth: '100%' }}\n      >\n        <div style={{ height: '500px', padding: '10px' }}>\n          {Array.from({ length: 50 }).map((_, i) => (\n            <p key={i}>Item {i + 1}: This is some scrollable content.</p>\n          ))}\n        </div>\n      </PerfectScrollbar>\n    </div>\n  );\n}\n\n// To render this:\n// ReactDOM.render(<MyScrollableComponent />, document.getElementById('root'));","lang":"typescript","description":"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."},"warnings":[{"fix":"Rename the prop from `option={...}` to `options={...}`.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Consult the `perfect-scrollbar` v1.4.0 release notes for specific behavior changes and adjust component usage or options accordingly.","message":"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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import PerfectScrollbar from 'react-perfect-scrollbar';` to correctly import the default export.","cause":"Incorrect import of the `PerfectScrollbar` component, often due to using `require()` or incorrect named vs. default import.","error":"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."},{"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.","cause":"The underlying perfect-scrollbar instance needs to be told to recalculate its dimensions after content changes.","error":"Scrollbar not visible or not updating when content changes."},{"fix":"Rename the prop from `option` to `options`.","cause":"Using the deprecated `option` prop instead of `options` for perfect-scrollbar configuration.","error":"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."},{"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.","cause":"The CSS file for `perfect-scrollbar` is not being imported or processed by the build system.","error":"Module not found: Can't resolve 'react-perfect-scrollbar/dist/css/styles.css' in '...' or Styles appear broken/missing."}],"ecosystem":"npm"}