@kwooshung/react-overlay-scrollbars-smooth

React Overlay Scrollbars Smooth

This integration plugin is based on OverlayScrollbars and smoothscroll-for-websites. It conceals the native scrollbars and provides a custom-styled overlay scrollbar that retains native functionality and feel, with the added benefit of inertial scrolling.

English | 中文

Why Develop It?

• I grew tired of the default browser scrollbars that look unappealing and vary across different browsers.
• They failed to maintain a consistent appearance and behavior across various browsers and lacked deep customization options.
• The default scrollbar doesn’t align with the design aesthetic of your website or application.
• When pop-ups are needed, the scrollbar appears outside the popup, causing both the page's scrollbar and the popup's scrollbar to appear simultaneously, leading to a poor user experience.
• When a Dialog/Modal pops up, it’s necessary to adjust the body’s padding-right, which requires special handling when the navigation bar is fixed, potentially causing jarring movements.
• The scrollbar feels stiff and not smooth enough when using the mouse wheel to scroll.

Installation

npm

npm install @kwooshung/react-overlay-scrollbars-smooth

yarn

yarn add @kwooshung/react-overlay-scrollbars-smooth

pnpm

pnpm add @kwooshung/react-overlay-scrollbars-smooth

Usage

Styles

In some frameworks, you can directly introduce styles in global css / less / scss, as shown below:

@import url('@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css');

In some frameworks, such as Next.js, you may need to add the ~ character, as shown below:

@import url('~@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css');

You can also introduce it in a global page, such as the Layout page in Next.js or the corresponding component, as shown below:

import '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';

components

Use the OverlayScrollbarsSmooth component on an element as follows:

import { OverlayScrollbarsSmooth } from '@kwooshung/react-overlay-scrollbars-smooth';

// What is used here is to introduce secondary styles directly into the component. You can also use other methods above.
import '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';

function App() {
  return (
    <div style={{ height: '300px' }}>
      <OverlayScrollbarsSmooth>
        <div style={{ height: '1000px' }} />
      </OverlayScrollbarsSmooth>
    </div>
  );
}

If you want it to work on Body, you can do this:

import { OverlayScrollbarsSmooth } from '@kwooshung/react-overlay-scrollbars-smooth';

function App() {
  // No matter where this line of code is written, as long as `tag=body`, it will act on `Body`, thus replacing the default scroll bar. Don’t forget to include styles!
  return <OverlayScrollbarsSmooth tag='body' />;
}

hooks

You can directly use useSmoothScroll to achieve smooth scrolling, which will cause all scroll bars to become smooth. It is recommended to call it once in a place such as global layout, as shown below:

import { OverlayScrollbarsSmooth, useSmoothScroll } from '@kwooshung/react-overlay-scrollbars-smooth';
import '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';

function App() {
  useSmoothScroll();

  return (
    <div style={{ height: '300px' }}>
      <OverlayScrollbarsSmooth>
        <div style={{ height: '1000px' }} />
      </OverlayScrollbarsSmooth>
    </div>
  );
}

API

OverlayScrollbarsSmooth

The OverlayScrollbarsSmooth component supports all OverlayScrollbars APIs, you can view OverlayScrollbars API here.

Properties	Description
tag	string, default value: div, if it is: body, acts on Body, thus replacing the default scroll bar. element equivalent to OverlayScrollbars;
className	string, default value: '', custom class name; invalid when tag=body;
options	Equivalent to options of OverlayScrollbars, default: {scrollbars: {theme: 'os-theme-dark'}}
events	Equivalent to events of OverlayScrollbars, default: {}

useSmoothScroll

Supports all parameters of smoothscroll-for-websites except excluded, you can view it here smoothscroll-for-websites API , the following parameters are also default values (it is slightly different from the default value of smoothscroll-for-websites), you can modify it according to your own needs, as shown below

import { OverlayScrollbarsSmooth, useSmoothScroll } from '@kwooshung/react-overlay-scrollbars-smooth';
import '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';

function App() {
  useSmoothScroll({
    // Scrolling Core
    frameRate: 150, // [ms]
    animationTime: 1000, // [ms]
    stepSize: 100, // [px]

    // Pulse (less tweakable)
    // ratio of "tail" to "acceleration"
    pulseAlgorithm: true,
    pulseScale: 4,
    pulseNormalize: true,

    // Acceleration
    accelerationDelta: 50,
    accelerationMax: 3,

    // Keyboard Settings
    keyboardSupport: true,
    arrowScroll: 50,

    // Other
    touchpadSupport: false, // ignore touchpad by default
    fixedBackground: true
  });

  return (
    <div style={{ height: '300px' }}>
      <OverlayScrollbarsSmooth>
        <div style={{ height: '1000px' }} />
      </OverlayScrollbarsSmooth>
    </div>
  );
}

Open source projects used

Thanks to the project authors for their selfless contributions to the open source community, making our work easier! ! !

• OverlayScrollbars：Excellent scroll bar custom component
• smoothscroll-for-websites：Excellent scroll bar smoothing script

LICENSE

MIT