{"id":11851,"library":"react-scrollbars-custom","title":"Custom Scrollbars for React","description":"react-scrollbars-custom is a React component that provides highly customizable scrollbars while preserving native browser scrolling behavior. Unlike many alternatives, it does not emulate scrolling but rather styles the native scrollbars, ensuring optimal performance (60 FPS using requestAnimationFrame) and a consistent experience across different browsers and platforms. Key features include cross-browser compatibility, full customizability for look and feel, scrollbar nesting, momentum scrolling for iOS, RTL support, and proper handling of page zoom. The current stable version is 4.1.1, released in August 2022, indicating a maintenance phase following active development. It differentiates itself by its performance-focused approach and extensive customization options, including allowing users to define their own renderer components.","status":"maintenance","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/xobotyi/react-scrollbars-custom","tags":["javascript","customizable","scrollbars","scroll","scrollbar","react","component","custom","typescript"],"install":[{"cmd":"npm install react-scrollbars-custom","lang":"bash","label":"npm"},{"cmd":"yarn add react-scrollbars-custom","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-scrollbars-custom","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for any React component. Version >=16.0.0 is required since v4.1.0.","package":"react","optional":false}],"imports":[{"note":"The library primarily uses ES Modules, though a CJS build is available via the 'main' field for older bundlers. TypeScript types are included.","wrong":"const Scrollbar = require('react-scrollbars-custom');","symbol":"Scrollbar","correct":"import { Scrollbar } from 'react-scrollbars-custom';"},{"note":"Import types using `import type` for better tree-shaking and clarity in TypeScript projects.","wrong":"import { ScrollbarProps } from 'react-scrollbars-custom';","symbol":"ScrollbarProps","correct":"import type { ScrollbarProps } from 'react-scrollbars-custom';"},{"note":"You can alias the default `Scrollbar` component if there's a naming conflict or for preference.","symbol":"CustomScrollbar","correct":"import { Scrollbar as CustomScrollbar } from 'react-scrollbars-custom';"}],"quickstart":{"code":"import React from 'react';\nimport { Scrollbar } from 'react-scrollbars-custom';\n\nfunction App() {\n  return (\n    <div style={{ width: '100%', height: 'calc(100vh - 20px)', padding: '10px' }}>\n      <h1>My Scrollable Content</h1>\n      <p>This component demonstrates a custom scrollbar that maintains native scrolling behavior but allows for extensive styling. It's often used when default browser scrollbars don't match the application's aesthetic.</p>\n      <Scrollbar style={{ width: '100%', height: 300, border: '1px solid #ccc', padding: '10px' }} noDefaultStyles>\n        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>\n        {Array.from({ length: 50 }).map((_, i) => (\n          <p key={i}>This is some scrollable content, line {i + 1}. Adding more lines to ensure the scrollbar appears and is functional.</p>\n        ))}\n        <p>End of scrollable content. You can scroll this section independently.</p>\n      </Scrollbar>\n      <h2>Another section below the scrollable area.</h2>\n      <p>This content is outside the custom scrollbar component.</p>\n    </div>\n  );\n}\n\nexport default App;\n","lang":"typescript","description":"This quickstart demonstrates how to integrate `Scrollbar` into a React component, setting its dimensions and populating it with content to enable scrolling. It also shows how to opt out of default styling."},"warnings":[{"fix":"Ensure your project uses React `>=16.0.0`. If you had custom `prop-types` validators for `react-scrollbars-custom` props, these may no longer be necessary or need to be adapted for TypeScript types.","message":"In `v4.1.0`, the `prop-types` dependency was removed. If your project explicitly relied on `prop-types` for `react-scrollbars-custom`, you might need to adjust your dependency configuration or type checking setup. This version also updated the peer dependency for React to `>=16.0.0`.","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"Always provide `width` and `height` to the `Scrollbar` component, e.g., `<Scrollbar style={{ width: 250, height: 250 }}>` or ensure they are applied via CSS.","message":"The `<Scrollbar />` component requires explicit `width` and `height` properties (either inline via `style` or through CSS classes) to function correctly and display scrollbars. Without defined dimensions, the component may not render scrollbars or behave as expected.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include `@babel/polyfill` or similar polyfills in your project if targeting IE10 or older browsers.","message":"For compatibility with Internet Explorer 10 and older browsers, polyfills (e.g., `@babel/polyfill`) are required. While the library is syntax-compatible with IE10+, it relies on modern browser APIs not natively available in these older environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to your bundler's documentation (e.g., Webpack `resolve.mainFields` or Babel `browserslist` configuration) to ensure the correct module version is used and transpiled for your target environments.","message":"The library ships with `main` (CJS ES3), `module` (ESM ES3), and `esnext` (ESM ES6+) fields in `package.json`. Depending on your bundler configuration (e.g., Webpack, Babel), you might need specific settings to correctly resolve and transpile the desired version, especially if you intend to leverage the untranspiled `esnext` version.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When using `noDefaultStyles`, provide your own CSS for visual customization. Be aware that certain layout-critical styles are always applied internally.","message":"Applying custom styles or disabling default styles using `noDefaultStyles` prop is possible, but some critical inline styles necessary for the component's proper functionality will always remain.","severity":"gotcha","affected_versions":">=2.2.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `<Scrollbar>` component has defined `width` and `height` styles (e.g., `style={{ width: 300, height: 200 }}`) or via CSS. Also, verify that the content inside the `Scrollbar` is larger than these dimensions to trigger scrolling.","cause":"The `Scrollbar` component does not have explicit `width` and `height` dimensions, or its content is not overflowing its boundaries.","error":"Scrollbar not appearing or not scrolling despite having content."},{"fix":"Ensure `react` is installed as a dependency and meets the `>=16.0.0` peer dependency requirement. Check your bundler configuration to ensure `react` is resolved correctly. For `react-scrollbars-custom v4.1.0` and above, the `prop-types` dependency was removed, which could also affect older setups.","cause":"This error typically indicates an issue with `React` peer dependency resolution or an incompatible `React` version, especially with older module bundlers or `react-scrollbars-custom` versions prior to `v4.1.0`.","error":"TypeError: Super expression must either be null or a function, not undefined."},{"fix":"Upgrade to `react-scrollbars-custom@4.1.1` or higher, which includes a fix to replace `global` with proper browser environment detection.","cause":"Using an older version of `react-scrollbars-custom` that did not correctly handle browser environment detection, leading to issues with server-side rendering (SSR) or specific browser builds.","error":"Syntax error or `global` is not defined in a browser environment."},{"fix":"Verify that `noDefaultStyles` is passed to the `<Scrollbar>` component. If providing custom renderers (e.g., for `renderThumbVertical`), ensure that essential styles are explicitly passed to your custom renderer components as described in the documentation, as some styles are crucial for functional correctness. Use higher CSS specificity for your custom styles if needed.","cause":"Either the custom styles are not specific enough to override the component's internal styles, or the `noDefaultStyles` prop is incorrectly applied or missing for the desired elements.","error":"Custom styles not applying or default styles persisting despite `noDefaultStyles`."}],"ecosystem":"npm"}