{"id":11678,"library":"react-custom-scrollbars","title":"React Custom Scrollbars","description":"react-custom-scrollbars is a React component library designed to replace native browser scrollbars with fully customizable alternatives, offering a consistent look and feel across different browsers and devices. It prioritizes performance with `requestAnimationFrame` for smooth scrolling and supports universal rendering (SSR). Key features include auto-hide, auto-height, and extensive styling options without requiring external stylesheets. The current stable version is 4.2.1. While not on a fixed release cadence, the project has seen consistent updates in its 4.x series, primarily focusing on React compatibility and bug fixes. It differentiates itself by its focus on native-like behavior, mobile support, and complete visual control, contrasting with simpler scroll solutions or those that inject complex CSS.","status":"active","version":"4.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/malte-wessel/react-custom-scrollbars","tags":["javascript","scroll","scroller","scrollbars","react-component","react","custom"],"install":[{"cmd":"npm install react-custom-scrollbars","lang":"bash","label":"npm"},{"cmd":"yarn add react-custom-scrollbars","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-custom-scrollbars","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for rendering React components.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"The package primarily uses named exports. A default import will result in an 'Element type is invalid' error.","wrong":"import Scrollbars from 'react-custom-scrollbars';","symbol":"Scrollbars","correct":"import { Scrollbars } from 'react-custom-scrollbars';"},{"note":"For CommonJS environments, destructuring the require call is the correct approach to access the named export.","wrong":"const Scrollbars = require('react-custom-scrollbars').default;","symbol":"Scrollbars (CommonJS)","correct":"const { Scrollbars } = require('react-custom-scrollbars');"},{"note":"Instance methods like `getScrollHeight`, `scrollToTop`, etc., are available on a ref to the Scrollbars component.","symbol":"Instance methods","correct":"this.scrollbars.getScrollHeight();"}],"quickstart":{"code":"import React, { Component } from 'react';\nimport { Scrollbars } from 'react-custom-scrollbars';\n\nclass CustomScrollbarExample extends Component {\n  render() {\n    // Simulate dynamic content that would typically exceed container height\n    const longContent = Array.from({ length: 50 }).map((_, i) => (\n      <p key={i} style={{ marginBottom: '8px', lineHeight: '1.4' }}>\n        This is line {i + 1} of scrollable content. It demonstrates how{' '}\n        <span style={{ fontWeight: 'bold' }}>react-custom-scrollbars</span> handles overflow{' '}\n        with its custom scroll mechanism. The content within the Scrollbars component will be\n        wrapped and managed.\n      </p>\n    ));\n\n    return (\n      <div style={{ padding: '20px', fontFamily: 'Arial, sans-serif', maxWidth: '800px', margin: '0 auto' }}>\n        <h1>Custom Scrollbar Example</h1>\n        <p>\n          Below is a `Scrollbars` component configured with a fixed width and height.\n          The content inside will scroll using the custom scrollbars provided by the library.\n        </p>\n        <div style={{ border: '1px solid #e0e0e0', borderRadius: '4px', overflow: 'hidden' }}>\n          <Scrollbars style={{ width: '100%', height: 300 }}>\n            {longContent}\n          </Scrollbars>\n        </div>\n        <p style={{ marginTop: '20px' }}>\n          This shows the basic usage, allowing for a visually consistent scroll experience\n          across different browsers and operating systems, with full control over the scrollbar's appearance.\n        </p>\n      </div>\n    );\n  }\n}\n\nexport default CustomScrollbarExample;","lang":"javascript","description":"Demonstrates a basic React class component utilizing `Scrollbars` with fixed dimensions to manage overflowing content, showcasing the default custom scrollbar appearance and behavior."},"warnings":[{"fix":"Review your custom track styling and 'autoHeight' related props. Explicitly set `heightTracksWhenNotNeeded={false}` if previous behavior (tracks always visible) is desired.","message":"Version 4.0.0 removed cursor styles from tracks and changed the default behavior for 'heightTracksWhenNotNeeded' and 'autoHeight'. Existing custom CSS or assumptions about track visibility might need adjustments.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Install the type definitions: `npm install --save-dev @types/react-custom-scrollbars` or `yarn add -D @types/react-custom-scrollbars`.","message":"Starting with v4.1.0, the package no longer ships its own TypeScript definition files (index.d.ts was removed). Projects using TypeScript will need to install `@types/react-custom-scrollbars` for type inference.","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"Check your 'package.json' for 'react' and 'react-dom' versions. Upgrade or downgrade React if necessary to match the peer dependency range. Use `npm install --force` or `yarn add --ignore-engines` with caution for minor mismatches.","message":"The package has peer dependencies on 'react' and 'react-dom' (>=0.14.0 || >=15.0.0 || >=16.0.0). Ensure your project's React version falls within these ranges to avoid compatibility issues, especially with newer React versions not explicitly listed.","severity":"gotcha","affected_versions":">=0.14.0"},{"fix":"Remove fixed height from the parent element of Scrollbars when `autoHeight` is enabled. Ensure the parent allows the Scrollbars to grow naturally based on its content.","message":"When using the `autoHeight` prop, ensure the parent container of the Scrollbars component does not have an explicit fixed height, as this can lead to unexpected sizing or scrolling behavior. `autoHeight` is designed for content-driven height.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Always add the prop `universal={true}` to your `<Scrollbars>` component when rendering in an SSR context.","message":"For server-side rendering (SSR) environments, the `universal` prop must be set to `true` to prevent issues with `window` and `document` object access during the initial render, which can cause hydration mismatches or errors.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `import Scrollbars from 'react-custom-scrollbars';` to `import { Scrollbars } from 'react-custom-scrollbars';`.","cause":"Attempting to use a default import instead of a named import for the Scrollbars component.","error":"Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object."},{"fix":"Ensure that any state updates or external event listeners attached to the Scrollbars component or its children are properly cleaned up in the component's `componentWillUnmount` or a `useEffect` cleanup function.","cause":"This warning often occurs when asynchronous operations (e.g., debounced scroll event handlers) attempt to update state on a React component that has already been unmounted. While not specific to `react-custom-scrollbars`, it's common when attaching custom event listeners to it.","error":"Warning: Can't perform a React state update on an unmounted component."},{"fix":"Ensure the ref is correctly assigned to the Scrollbars component (e.g., `<Scrollbars ref={this.scrollbarsRef}>`) and accessed only after the component has mounted (e.g., in `componentDidMount` or a `useEffect` hook with a dependency array checking for ref's existence).","cause":"Attempting to access Scrollbars instance methods (e.g., `getScrollHeight`, `scrollToTop`) via a ref before the component has fully mounted or if the ref is not correctly assigned.","error":"TypeError: Cannot read properties of undefined (reading 'getScrollHeight')"}],"ecosystem":"npm"}