react-custom-scrollbars

What is react-custom-scrollbars?

The react-custom-scrollbars package provides a customizable scrollbar component for React applications. It allows developers to create scrollbars with custom styles and behaviors, enhancing the user experience by providing more control over the appearance and functionality of scrollable areas.

What are react-custom-scrollbars's main functionalities?

Custom Scrollbars

This feature allows you to create a custom scrollbar for a scrollable area. You can specify the dimensions and style of the scrollbar.

import { Scrollbars } from 'react-custom-scrollbars';

function CustomScrollbar() {
  return (
    <Scrollbars style={{ width: 500, height: 300 }}>
      <div>Your content here</div>
    </Scrollbars>
  );
}

Custom Thumb Renderer

This feature allows you to customize the appearance of the scrollbar thumb. You can provide a custom renderer for the thumb component.

import { Scrollbars } from 'react-custom-scrollbars';

function CustomThumb({ style, ...props }) {
  const thumbStyle = {
    backgroundColor: 'blue',
    borderRadius: '4px'
  };
  return <div style={{ ...style, ...thumbStyle }} {...props} />;
}

function CustomScrollbar() {
  return (
    <Scrollbars renderThumbVertical={props => <CustomThumb {...props} />} style={{ width: 500, height: 300 }}>
      <div>Your content here</div>
    </Scrollbars>
  );
}

Custom Track Renderer

This feature allows you to customize the appearance of the scrollbar track. You can provide a custom renderer for the track component.

import { Scrollbars } from 'react-custom-scrollbars';

function CustomTrack({ style, ...props }) {
  const trackStyle = {
    backgroundColor: 'lightgray',
    borderRadius: '4px'
  };
  return <div style={{ ...style, ...trackStyle }} {...props} />;
}

function CustomScrollbar() {
  return (
    <Scrollbars renderTrackVertical={props => <CustomTrack {...props} />} style={{ width: 500, height: 300 }}>
      <div>Your content here</div>
    </Scrollbars>
  );
}

Custom View Renderer

This feature allows you to customize the appearance of the scrollable view. You can provide a custom renderer for the view component.

import { Scrollbars } from 'react-custom-scrollbars';

function CustomView({ style, ...props }) {
  const viewStyle = {
    padding: '10px'
  };
  return <div style={{ ...style, ...viewStyle }} {...props} />;
}

function CustomScrollbar() {
  return (
    <Scrollbars renderView={props => <CustomView {...props} />} style={{ width: 500, height: 300 }}>
      <div>Your content here</div>
    </Scrollbars>
  );
}

Other packages similar to react-custom-scrollbars

react-scrollbars-custom

react-scrollbars-custom is a highly customizable scrollbar component for React. It offers more flexibility and customization options compared to react-custom-scrollbars, including support for horizontal and vertical scrollbars, custom thumb and track components, and more.

react-perfect-scrollbar

react-perfect-scrollbar is a React wrapper for the Perfect Scrollbar library. It provides a simple and easy-to-use interface for adding custom scrollbars to your React applications. It is less customizable than react-custom-scrollbars but offers a straightforward solution for adding custom scrollbars.

react-scrollbar

react-scrollbar is another customizable scrollbar component for React. It provides basic customization options for the scrollbar's appearance and behavior. It is simpler and less feature-rich compared to react-custom-scrollbars but can be a good choice for basic use cases.

README

react-custom-scrollbars

• lightweight scrollbars made of 100% react goodness
• frictionless native browser scrolling
• native scrollbars for mobile devices
• fully customizable
• requestAnimationFrame for 60fps
• no extra stylesheets
• IE9+ support
• check out the demo

Table of Contents

• Installation
• Usage
• Customization
• API
• Examples
• Tests
• License

Installation

npm install react-custom-scrollbars --save

Usage

import { Scrollbars } from 'react-custom-scrollbars';

class App extends Component {
  render() {
    return (
      <Scrollbars style={{ width: 500, height: 300 }}>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
      </Scrollbars>
    );
  }
}

Don't forget to set the viewport meta tag, if you want to support mobile devices

<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"/>

Customization

import { Scrollbars } from 'react-custom-scrollbars';

class CustomScrollbars extends Component {
  render() {
    return (
      <Scrollbars
        className="container"
        renderScrollbarHorizontal={props => <div {...props} className="scrollbar-horizontal" />}
        renderScrollbarVertical={props => <div {...props} className="scrollbar-vertical"/>}
        renderThumbHorizontal={props => <div {...props} className="thumb-horizontal"/>}
        renderThumbVertical={props => <div {...props} className="thumb-vertical"/>}
        renderView={props => <div {...props} className="view"/>}>
        {this.props.children}
      </Scrollbars>
    );
  }
}

class App extends Component {
  render() {
    return (
      <CustomScrollbars style={{ width: 500, height: 300 }}>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
        <p>Lorem ipsum dolor sit amet, ...</p>
      </CustomScrollbars>
    );
  }
}

API

<Scrollbars>

Props

• onScroll: (Function) Event handler. Will be called with the native scroll event and some handy values about the current position.
  • Signature: onScroll(event, values)
  • event: (Event) Native onScroll event
  • values: (Object) Values about the current position
    • values.top: (Number) scrollTop progess, from 0 to 1
    • values.left: (Number) scrollLeft progess, from 0 to 1
    • values.clientWidth: (Number) width of the view
    • values.clientHeight: (Number) height of the view
    • values.scrollWidth: (Number) native scrollWidth
    • values.scrollHeight: (Number) native scrollHeight
    • values.scrollLeft: (Number) native scrollLeft
    • values.scrollTop: (Number) native scrollTop
• The following properties expect a react element to be returned. You can customize the element to your needs.
• renderScrollbarHorizontal: (Function) Horizontal scrollbar element
• renderScrollbarVertical: (Function) Vertical scrollbar element
• renderThumbHorizontal: (Function) Horizontal thumb element
• renderThumbVertical: (Function) Vertical thumb element
• renderView: (Function) The element your content will be rendered in

Don't forget to pass the received props to your custom element. Example:

import { Scrollbars } from 'react-custom-scrollbars';

class CustomScrollbars extends Component {
  render() {
    return (
      <Scrollbars
        // Set a custom className
        renderScrollbarHorizontal={props => <div {...props} className="scrollbar-vertical"/>}
        // Customize inline styles
        renderScrollbarVertical={({ style, ...props}) => {
          return <div style={{...style, padding: 20}} {...props}/>;
        }}>
        {this.props.children}
      </Scrollbars>
    );
  }
}

Methods

• scrollTop(top): scroll to the top value
• scrollLeft(left): scroll to the left value
• scrollToTop(): scroll to top
• scrollToBottom(): scroll to bottom
• scrollToLeft(): scroll to left
• scrollToRight(): scroll to right
• getScrollLeft: get scrollLeft value
• getScrollTop: get scrollTop value
• getScrollWidth: get scrollWidth value
• getScrollHeight: get scrollHeight value
• getWidth: get view client width
• getHeight: get view client height

import { Scrollbars } from 'react-custom-scrollbars';

class App extends Component {
  handleClick() {
    this.refs.scrollbars.scrollToTop()
  },
  render() {
    return (
      <div>
        <Scrollbars
          ref="scrollbars"
          style={{ width: 500, height: 300 }}>
          {/* your content */}
        </Scrollbars>
        <button onClick={this.handleClick.bind(this)}>
            Scroll to top
        </button>
      </div>
    );
  }
}

Receive values about the current position

class CustomScrollbars extends Component {
  handleScroll(event, values) {
    console.log(values);
    /*
    {
        left: 0,
        top: 0.21513353115727002
        clientWidth: 952
        clientHeight: 300
        scrollWidth: 952
        scrollHeight: 1648
        scrollLeft: 0
        scrollTop: 290
    }
    */
  }
  render() {
    return (
      <Scrollbars onScroll={this.handleScroll}>
        {this.props.children}
      </Scrollbars>
    );
  }
}

Examples

Run the simple example:

# Make sure that you've installed the dependencies
npm install
# Move to example directory
cd react-custom-scrollbars/examples/simple
npm install
npm start

Tests

# Make sure that you've installed the dependencies
npm install
# Run tests
npm test

License

MIT