https://github.com/kwooshung/react-overlay-scrollbars-smooth
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.
https://github.com/kwooshung/react-overlay-scrollbars-smooth
overlay react react-scroll react-scrollbar scroll scrollbar smooth
Last synced: 3 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/kwooshung/react-overlay-scrollbars-smooth
- Owner: kwooshung
- License: mit
- Created: 2024-02-05T07:36:21.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-05T16:07:19.000Z (over 1 year ago)
- Last Synced: 2025-03-30T18:01:42.164Z (3 months ago)
- Topics: overlay, react, react-scroll, react-scrollbar, scroll, scrollbar, smooth
- Language: JavaScript
- Homepage:
- Size: 170 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelogs/.history
- License: LICENSE
Awesome Lists containing this project
README
# React Overlay Scrollbars Smooth
This integration plugin is based on [OverlayScrollbars](https://github.com/KingSora/OverlayScrollbars/) and [smoothscroll-for-websites](https://github.com/gblazex/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.
[](LICENSE)
[](https://www.npmjs.com/package/@kwooshung/react-overlay-scrollbars-smooth)
[](https://www.npmjs.com/package/@kwooshung/react-overlay-scrollbars-smooth)
[](https://github.com/kwooshung/react-overlay-scrollbars-smooth/actions/)
[](https://codecov.io/gh/kwooshung/react-overlay-scrollbars-smooth)
[](https://codeclimate.com/github/kwooshung/react-overlay-scrollbars-smooth/maintainability/)
[](https://gitee.com/kwooshung/react-overlay-scrollbars-smooth/)
## 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
```bash
npm install @kwooshung/react-overlay-scrollbars-smooth
```
### yarn
```bash
yarn add @kwooshung/react-overlay-scrollbars-smooth
```
### pnpm
```bash
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:
```css
@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:
```css
@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:
```tsx
import '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';
```
### components
Use the `OverlayScrollbarsSmooth` component on an element as follows:
```tsx
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 (
);
}
```
If you want it to work on `Body`, you can do this:
```tsx
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 ;
}
```
### 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:
```tsx
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 (
);
}
```
### API
#### OverlayScrollbarsSmooth
The `OverlayScrollbarsSmooth` component supports all `OverlayScrollbars` APIs, you can view [OverlayScrollbars API](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react#properties) 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](https://github.com/gblazex/smoothscroll-for-websites/wiki) , 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
```tsx
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 (
);
}
```
## 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](https://github.com/KingSora/OverlayScrollbars/)
- [smoothscroll-for-websites：Excellent scroll bar smoothing script](https://github.com/gblazex/smoothscroll-for-websites)
## LICENSE
[MIT](LICENSE)