React Custom Scrollbar

A lightweight, highly customizable React scrollbar component with TypeScript support, accessibility features, and cross-browser compatibility.

![npm version](https://badge.fury.io/js/@openabir/react-custom-scrollbar-lite)
![License: MIT](https://opensource.org/licenses/MIT)
![TypeScript](https://github.com/ellerbrock/typescript-badges/)

✨ Features

- 🪶 Lightweight: Only ~5.1 KB gzipped
- 🎨 Fully Customizable: Style with CSS or styled-components
- ♿ Accessible: Built-in ARIA support and keyboard navigation
- 📱 Cross-browser: Works on all modern browsers
- 🔒 TypeScript: Full TypeScript support with type definitions
- ⚡ Performant: Optimized for smooth scrolling experience
- 🎯 Zero Dependencies: No external runtime dependencies (except React)
- 🔄 Auto-hide: Scrollbars can hide when not in use
- 📏 Auto-height: Support for automatic height adjustment
- 🌍 Universal: SSR/SSG compatible

📦 Installation

bash

npm install @openabir/react-custom-scrollbar-lite

or

bash

yarn add @openabir/react-custom-scrollbar-lite





🚀 Quick Start

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";



function App() {

  return (

    

      

        {/ Your scrollable content /}

        Long content that will be scrollable...

        More content...

        Even more content...

      

    

  );

}



export default App;





📚 API Reference



$3



| Prop                      | Type                             | Default                | Description                                |

| ------------------------- | -------------------------------- | ---------------------- | ------------------------------------------ |

|

children | ReactNode

                      | -                      | Content to be scrolled                     |

|

style | CSSProperties | {}

                   | Custom styles for the container            |

|

className | string

                         | -                      | CSS class name for the container           |

|

autoHide | boolean | false

                | Hide scrollbars when not scrolling         |

|

autoHideTimeout | number | 1000

                 | Time in ms before hiding scrollbars        |

|

autoHideDuration | number | 200

                  | Duration of hide animation (ms)            |

|

thumbMinSize | number | 30

                   | Minimum size of scroll thumb in pixels     |

|

universal | boolean | false

                | Enable universal rendering (SSR)           |

|

autoHeight | boolean | false

                | Automatically adjust height to content     |

|

autoHeightMin | number \| string | 0

                    | Minimum height when autoHeight is enabled  |

|

autoHeightMax | number \| string | 200

                  | Maximum height when autoHeight is enabled  |

|

hideTracksWhenNotNeeded | boolean | false

                | Hide tracks when not needed                |

|

renderThumbHorizontal | (props: any) => ReactElement

   | -                      | Custom horizontal thumb component          |

|

renderThumbVertical | (props: any) => ReactElement

   | -                      | Custom vertical thumb component            |

|

renderTrackHorizontal | (props: any) => ReactElement

   | -                      | Custom horizontal track component          |

|

renderTrackVertical | (props: any) => ReactElement

   | -                      | Custom vertical track component            |

|

renderView | (props: any) => ReactElement

   | -                      | Custom view component                      |

|

onScroll | (event: Event) => void

         | -                      | Scroll event handler                       |

|

onScrollFrame | (values: ScrollValues) => void

 | -                      | Called on each scroll frame                |

|

onScrollStart | () => void

                     | -                      | Called when scrolling starts               |

|

onScrollStop | () => void

                     | -                      | Called when scrolling stops                |

|

onUpdate | (values: ScrollValues) => void

 | -                      | Called when scroll values update           |

|

a11yEnabled | boolean | true

                 | Enable accessibility features              |

|

ariaLabel | string | 'Scrollable content'

 | ARIA label for the scrollbar               |

|

keyboardScrollAmount | number | 40

                   | Scroll amount (px) for keyboard navigation |



$3

typescript

interface ScrollValues {

  top: number; // Scroll top position (0-1)

  left: number; // Scroll left position (0-1)

  clientWidth: number; // Width of the view

  clientHeight: number; // Height of the view

  scrollWidth: number; // Total scrollable width

  scrollHeight: number; // Total scrollable height

  scrollLeft: number; // Current horizontal scroll position

  scrollTop: number; // Current vertical scroll position

}





🎨 Styling



$3

css

/ Container /

.custom-scrollbar {

  / Your styles /

}



/ Vertical track /

.custom-scrollbar .track-vertical {

  background: rgba(0, 0, 0, 0.1);

  width: 8px;

  right: 2px;

  bottom: 2px;

  top: 2px;

  border-radius: 4px;

}



/ Vertical thumb /

.custom-scrollbar .thumb-vertical {

  background: rgba(0, 0, 0, 0.5);

  border-radius: 4px;

  cursor: pointer;

}



/ Horizontal track /

.custom-scrollbar .track-horizontal {

  background: rgba(0, 0, 0, 0.1);

  height: 8px;

  left: 2px;

  right: 2px;

  bottom: 2px;

  border-radius: 4px;

}



/ Horizontal thumb /

.custom-scrollbar .thumb-horizontal {

  background: rgba(0, 0, 0, 0.5);

  border-radius: 4px;

  cursor: pointer;

}

$3

tsx

import Scrollbar from "react-custom-scrollbar";



const CustomScrollbar = () => (

      renderThumbVertical={({ style, ...props }) => (



    )}

    renderTrackVertical={({ style, ...props }) => (



    )}

  >

    {/ Content /}

  

);





🔧 Advanced Usage



$3

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";



const App = () => {

  return (

    

      

        

          {/ Your content here /}

          Scrollable content

        

      

    

  );

};



export default App;

$3

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";



const App = () => {

  return (

    

      

        

          {/ Your content here /}

          Scrollable content with auto-hiding scrollbars

        

      

    

  );

};



export default App;

$3

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";



const App = () => {

  // Custom components for scrollbar parts

  const renderThumbVertical = ({ style, ...props }) => {

    const thumbStyle = {

      ...style,

      backgroundColor: "#6e8efb",

      borderRadius: 6,

    };

    return

;

  };



  const renderTrackVertical = ({ style, ...props }) => {

    const trackStyle = {

      ...style,

      backgroundColor: "#f1f1f1",

      borderRadius: 6,

    };

    return

;

  };



  return (

    

              renderThumbVertical={renderThumbVertical}

        renderTrackVertical={renderTrackVertical}

        thumbMinSize={40}

      >

        

          {/ Your content here /}

          Scrollable content with custom styled scrollbars

        

      

    

  );

};



export default App;

$3

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";

import { ScrollValues } from "@openabir/react-custom-scrollbar-lite";



const App = () => {

  const handleScrollStart = () => {

    console.log("Scrolling started");

  };



  const handleScrollStop = () => {

    console.log("Scrolling stopped");

  };



  const handleScroll = (values: ScrollValues) => {

    console.log("Scroll position:", values.top, values.left);

  };



  return (

    

              onScrollStart={handleScrollStart}

        onScrollStop={handleScrollStop}

        onScroll={handleScroll}

      >

        

          {/ Your content here /}

          Scrollable content with scroll event handlers

        

      

    

  );

};



export default App;

$3

tsx

import React from "react";

import Scrollbar from "@openabir/react-custom-scrollbar-lite";



const App = () => {

  return (

    

      

        

          {/ Your content here /}

          Content with auto-height scrollbar

          {/ More content... /}

        

      

    

  );

};



export default App;





♿ Accessibility



The scrollbar component includes built-in accessibility features:



- ARIA attributes: Proper ARIA roles and properties

- Keyboard navigation: Arrow keys, Page Up/Down, Home/End

- Focus management: Proper focus handling for screen readers

- High contrast support: Respects OS high contrast settings



$3



-

↑/↓

 - Scroll vertically

-

←/→

 - Scroll horizontally

-

Page Up/Page Down

 - Scroll by page

-

Home/End

 - Scroll to start/end

tsx

  a11yEnabled={true} // Enabled by default

  ariaLabel="Custom scrollable content"

  keyboardScrollAmount={60} // Custom scroll amount for keyboard navigation

>

  Content





🌐 Browser Support



This component is compatible with the following browsers:



| Browser        | Minimum Version      |

| -------------- | -------------------- |

| Chrome         | 61+                  |

| Firefox        | 60+                  |

| Safari         | 12.1+                |

| Edge           | 79+ (Chromium-based) |

| IE             | Not supported        |

| Opera          | 48+                  |

| iOS Safari     | 12.2+                |

| Android Chrome | 76+                  |



🔧 Polyfills



The component uses modern browser APIs that might require polyfills for older browsers:



-

ResizeObserver

 (Required for auto-resize functionality)

- CSS Variables (Used for styling)

- Passive Event Listeners (Used for performance optimization)



For older browsers, you may need to include polyfills:

bash

npm install resize-observer-polyfill





Then import and use the polyfill in your application entry point:

javascript

import { setupPolyfills } from "@openabir/react-custom-scrollbar-lite";



// Setup all polyfills

setupPolyfills();





📱 Server-Side Rendering (SSR)



The component supports SSR out of the box. For Next.js:

tsx

import dynamic from "next/dynamic";



const Scrollbar = dynamic(() => import("react-custom-scrollbar"), {

  ssr: false,

});





🎯 Performance Tips



1. Use auto-hide: Reduces DOM updates when not scrolling

2. Minimize re-renders: Use

React.memo

 for content components

3. Optimize content: Use virtualization for large lists

4. Throttle events: Throttle scroll event handlers if needed



📖 Examples



Check out the examples directory for more usage examples:



- Basic Usage

- Custom Styling

- Auto-hide Functionality

- Event Handlers



🔬 Development



$3



Run the test suite:

bash

npm test





Run tests with coverage:

bash

npm run test:coverage





$3



Run performance benchmarks:

bash

npm run benchmark

``

See the benchmarks README for more information on performance testing.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Created with ❤️ by openabir

📈 Changelog

See CHANGELOG.md for a list of changes and version history.

🐛 Issues

Found a bug? Please open an issue on GitHub.

💬 Support

- 📖 Documentation
- 🐛 Issue Tracker
- 💡 Feature Requests

---

Keywords: react, scrollbar, scroll, typescript, component, ui, accessibility, cross-browser, lightweight, customizable