Registry / web-framework / react-perfect-scrollbar

react-perfect-scrollbar

library1.5.8jsnpmunverified

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.

web-framework

npm install react-perfect-scrollbar

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-PERFECT-SCRO

react-perfect-scrollbar

web-frameworkjavascriptv1.5.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PerfectScrollbar

✓ import PerfectScrollbar from 'react-perfect-scrollbar';

✗ const PerfectScrollbar = require('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

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

✗ require('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

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

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

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

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'));

Debug

Known issues

breakingThe `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={...}`.

affects: >=1.5.0

breakingThe 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.

affects: >=1.4.0

gotchaWhen 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.

affects: >=1.0.0

gotchaOmitting 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.

affects: >=1.0.0

Errors

Common errors & fixes

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.

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.

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.

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.

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.

Upgrade

Version history

1.5.8latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications.

react-domrequiredPeer dependency for React applications.

perfect-scrollbarrequiredCore underlying scrollbar library.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/goldenyz/react-perfect-scrollbar ↗

packagehttps://www.npmjs.com/package/react-perfect-scrollbar ↗