@kwooshung/react-overlay-scrollbars-smooth
v2.0.2
Published
A React scrollbar custom component that hides the native scrollbar, provides a custom style overlay scrollbar, and retains the native functionality and feel while having scrolling inertia.
Downloads
274
Maintainers
Readme
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.
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