react-custom-scrollbars

react-custom-scrollbars provides a single <Scrollbars> component that wraps content in a native, momentum-scrolling container while giving full control over the visual track and thumb elements rendered on top — instead of hijacking scroll events with a JavaScript-driven fake scroller, it relies on requestAnimationFrame to keep custom scrollbar visuals in sync with the browser’s real scroll position. This keeps mobile devices’ native touch scrolling and momentum intact, supports server-side rendering (“universal” mode), and exposes render props for every visual piece (renderView, renderTrackHorizontal, renderThumbVertical, etc.) so teams can theme scrollbars to match their design system without extra stylesheets.

What You Get

• A <Scrollbars> component accepting arbitrary children and standard container styles (style={{ width, height }})
• Render props for every visual part — renderView, renderTrackHorizontal, renderTrackVertical, renderThumbHorizontal, renderThumbVertical — for full custom theming
• autoHide/autoHideTimeout/autoHideDuration props to fade scrollbars out when not scrolling, matching OS-style auto-hiding scrollbars
• autoHeight/autoHeightMin/autoHeightMax props so the container grows to fit content up to a bound instead of requiring a fixed height
• Scroll event callbacks (onScroll, onScrollFrame, onScrollStart, onScrollStop, onUpdate) plus imperative methods (scrollTop, scrollToTop, scrollToBottom, getValues) via a component ref

Common Use Cases

• Restyling browser scrollbars to match a design system (thin, colored, rounded thumbs) without losing native touch/momentum scrolling on mobile
• Building auto-hiding scrollbars for chat panels, sidebars, or code viewers that only appear while the user is actively scrolling
• Rendering scrollable panels whose height should grow with content up to a maximum, using autoHeight
• Server-rendering a page containing scrollable regions via the universal prop so markup matches between server and client before hydration

Under The Hood

Architecture The component (src/Scrollbars/index.js, ~650 lines) wraps children in a real, natively-scrollable DOM container and layers custom track/thumb elements on top via absolute positioning; a requestAnimationFrame loop reads the native container’s actual scrollTop/scrollLeft/scrollHeight each frame and updates the custom thumb size/position to match, so the real browser scrollbar is hidden (via negative-margin CSS in styles.js) while native touch/wheel/keyboard scrolling continues to drive everything.

Tech Stack Written in ES2015+ JavaScript (class components, pre-hooks React era) transpiled with Babel, bundled to both a CommonJS lib/ build and a UMD dist/ bundle via Webpack, tested with Karma plus a code-coverage run, and linted with ESLint; it has no runtime dependencies beyond React/ReactDOM peer dependencies.

Code Quality The README advertises 100% test coverage via the Karma-based test suite, the component’s prop surface is fully documented in a separate docs/API.md, and the render-prop pattern for each visual piece (renderView, renderTrackHorizontal, etc.) keeps default and custom rendering paths cleanly separated, though the codebase predates React hooks/function components and has seen no functional commits since its last 2017 release.

API Design A single <Scrollbars> component covers the common case with zero configuration (just wrap children and set a size), while render props for each visual element and imperative ref methods (scrollTop, getValues) cover advanced theming and programmatic scroll control, keeping the basic API approachable while still supporting deep customization for teams that need it.