react-custom-scrollbars

Modern React scrollbars component with TypeScript support and React 19 compatibility.

✨ Features

• 🚀 Modern React Hooks - Built with React hooks and TypeScript
• 📱 Native mobile scrolling - Native scrollbars for mobile devices
• 🎨 Fully customizable - Complete control over scrollbar appearance
• 🔄 Auto hide - Configurable auto-hide functionality
• 📏 Auto height - Dynamic height based on content
• 🌐 Universal - SSR compatible (runs on client & server)
• ⚡ 60fps performance - Smooth scrolling with requestAnimationFrame
• 🎯 Zero dependencies - No external dependencies in production
• 📘 TypeScript ready - Full TypeScript support with proper types
• ✅ Well tested - Comprehensive test coverage

📦 Installation

npm install @dev-ahmed-mahmoud/react-custom-scrollbars

Package Info:

• 📋 Package: @dev-ahmed-mahmoud/react-custom-scrollbars
• 🌐 Registry: npm
• 📊 Bundle size: ~18KB (5.4KB gzipped)
• 🏷️ License: MIT

🚀 Usage

Basic Example

import React from 'react'
import { Scrollbars } from '@dev-ahmed-mahmoud/react-custom-scrollbars'

function App() {
  return (
    <Scrollbars style={{ width: 500, height: 300 }}>
      <p>Some great content...</p>
    </Scrollbars>
  )
}

Advanced Example with TypeScript

import React, { useRef } from 'react'
import { Scrollbars, ScrollbarsRef, ScrollValues } from '@dev-ahmed-mahmoud/react-custom-scrollbars'

function CustomScrollbars() {
  const scrollbars = useRef<ScrollbarsRef>(null)

  const handleScrollFrame = (values: ScrollValues) => {
    const { top } = values
    if (top > 0.8) {
      console.log('Near bottom!')
    }
  }

  const scrollToTop = () => {
    scrollbars.current?.scrollToTop()
  }

  return (
    <div>
      <button onClick={scrollToTop}>Scroll to top</button>
      <Scrollbars
        ref={scrollbars}
        onScrollFrame={handleScrollFrame}
        renderThumbVertical={({ style, ...props }) => (
          <div
            style={{
              ...style,
              backgroundColor: '#007bff',
              borderRadius: '3px',
            }}
            {...props}
          />
        )}
        style={{ width: 500, height: 300 }}
      >
        <div style={{ padding: 20 }}>
          {Array.from({ length: 50 }, (_, i) => (
            <p key={i}>Content line {i + 1}</p>
          ))}
        </div>
      </Scrollbars>
    </div>
  )
}

📚 API Reference

Props

Prop	Type	Default	Description
onScroll	(event: Event) => void	-	Event handler for scroll events
onScrollFrame	(values: ScrollValues) => void	-	Runs inside the animation frame
onScrollStart	() => void	-	Called when scrolling starts
onScrollStop	() => void	-	Called when scrolling stops
onUpdate	(values: ScrollValues) => void	-	Called when component updates
renderView	(props: RenderElementProps) => ReactElement	-	Custom view component
renderTrackHorizontal	(props: RenderElementProps) => ReactElement	-	Custom horizontal track
renderTrackVertical	(props: RenderElementProps) => ReactElement	-	Custom vertical track
renderThumbHorizontal	(props: RenderElementProps) => ReactElement	-	Custom horizontal thumb
renderThumbVertical	(props: RenderElementProps) => ReactElement	-	Custom vertical thumb
hideTracksWhenNotNeeded	boolean	false	Hide tracks when content doesn't overflow
thumbSize	number	-	Fixed thumb size in px
thumbMinSize	number	30	Minimum thumb size in px
autoHide	boolean	false	Enable auto-hide mode
autoHideTimeout	number	1000	Hide delay in ms
autoHideDuration	number	200	Duration for hide animation in ms
autoHeight	boolean	false	Enable auto-height mode
autoHeightMin	number | string	0	Minimum height for auto-height mode
autoHeightMax	number | string	200	Maximum height for auto-height mode
universal	boolean	false	Enable universal/SSR rendering
tagName	string	'div'	Container element tag name

Ref Methods

The component provides imperative methods through refs:

interface ScrollbarsRef {
  getScrollLeft(): number
  getScrollTop(): number
  getScrollWidth(): number
  getScrollHeight(): number
  getClientWidth(): number
  getClientHeight(): number
  getValues(): ScrollValues
  scrollLeft(left?: number): void
  scrollTop(top?: number): void
  scrollToLeft(): void
  scrollToTop(): void
  scrollToRight(): void
  scrollToBottom(): void
}

🛠️ Development

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

# Lint code
npm run lint

# Format code
npm run format

📝 Migration from v4

This is a major version with breaking changes:

Breaking Changes

• Node.js 18+ required
• React 18+ required
• Component converted to hooks (no more class component)
• TypeScript first (JavaScript still supported)
• ES modules only (no UMD build)
• Removed deprecated props and methods

Methods (via ref)

Method	Description
scrollTop(top: number)	Scroll to specific top position
scrollLeft(left: number)	Scroll to specific left position
scrollToTop()	Scroll to top
scrollToBottom()	Scroll to bottom
scrollToLeft()	Scroll to left
scrollToRight()	Scroll to right
getScrollLeft()	Get current scrollLeft value
getScrollTop()	Get current scrollTop value
getScrollWidth()	Get scrollable width
getScrollHeight()	Get scrollable height
getClientWidth()	Get view client width
getClientHeight()	Get view client height
getValues()	Get current scroll values object

📋 Requirements

• Node.js: 20.0.0 or higher
• React: 18.0.0 or higher (React 19 supported)
• TypeScript: 5.8+ (optional, but recommended)

📖 Documentation

• API Reference - Complete API documentation
• Customization Guide - Learn how to customize scrollbars
• Usage Examples - More usage examples
• Upgrade Guide - Migrating from v4.x to v5.0

🚀 Migration from v4.x

Version 5.0 maintains API compatibility while modernizing the internals:

// ✅ Your existing v4 code mostly works as-is
<Scrollbars
  style={{ width: 500, height: 300 }}
  autoHide
  autoHideTimeout={1000}
  onScrollStart={() => console.log('Started')}
  onScrollStop={() => console.log('Stopped')}
>
  {content}
</Scrollbars>

Key Changes:

• Now requires React 18+ and Node.js 20+
• Written in TypeScript with built-in types
• Modern hooks-based implementation
• ES modules only (no CommonJS)
• Smaller bundle size and better performance

See the complete upgrade guide for details.

🔄 Changelog

See CHANGELOG.md for version history and breaking changes.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

MIT © Malte Wessel (original author)

v5.0 modernization by Ahmed Mahmoud