{"id":23094185,"url":"https://github.com/kwooshung/react-overlay-scrollbars-smooth","last_synced_at":"2026-05-02T19:33:20.163Z","repository":{"id":220991804,"uuid":"752960749","full_name":"kwooshung/react-overlay-scrollbars-smooth","owner":"kwooshung","description":"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.","archived":false,"fork":false,"pushed_at":"2024-02-05T16:07:19.000Z","size":174,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T18:50:30.657Z","etag":null,"topics":["overlay","react","react-scroll","react-scrollbar","scroll","scrollbar","smooth"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kwooshung.png","metadata":{"files":{"readme":"README.md","changelog":"changelogs/.history","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-02-05T07:36:21.000Z","updated_at":"2024-04-02T21:47:50.000Z","dependencies_parsed_at":"2024-02-05T16:20:15.838Z","dependency_job_id":"d89ec653-b2df-4256-9411-469e33434f35","html_url":"https://github.com/kwooshung/react-overlay-scrollbars-smooth","commit_stats":null,"previous_names":["kwooshung/react-overlay-scrollbars-smooth"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kwooshung/react-overlay-scrollbars-smooth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2Freact-overlay-scrollbars-smooth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2Freact-overlay-scrollbars-smooth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2Freact-overlay-scrollbars-smooth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2Freact-overlay-scrollbars-smooth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kwooshung","download_url":"https://codeload.github.com/kwooshung/react-overlay-scrollbars-smooth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2Freact-overlay-scrollbars-smooth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32547647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T19:18:06.202Z","status":"ssl_error","status_checked_at":"2026-05-02T19:16:21.335Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["overlay","react","react-scroll","react-scrollbar","scroll","scrollbar","smooth"],"created_at":"2024-12-16T21:57:33.243Z","updated_at":"2026-05-02T19:33:20.140Z","avatar_url":"https://github.com/kwooshung.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# React Overlay Scrollbars Smooth\n\nThis 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.\n\n[![GitHub License](https://img.shields.io/github/license/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)](LICENSE)\n![GitHub Release Date - Published_At](https://img.shields.io/github/release-date/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=00b42A\u0026logo=github)\n![GitHub last commit](https://img.shields.io/github/last-commit/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n![GitHub top language](https://img.shields.io/github/languages/top/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n![GitHub issues](https://img.shields.io/github/issues/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n![Github Stars](https://img.shields.io/github/stars/kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)\n[![NPM Version](https://img.shields.io/npm/v/@kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026color=165dff)](https://www.npmjs.com/package/@kwooshung/react-overlay-scrollbars-smooth)\n[![Npm.js Downloads/Week](https://img.shields.io/npm/dw/@kwooshung/react-overlay-scrollbars-smooth?labelColor=272e3b\u0026labelColor=272e3b\u0026color=165dff\u0026logo=npm)](https://www.npmjs.com/package/@kwooshung/react-overlay-scrollbars-smooth)\n[![Github CI/CD](https://github.com/kwooshung/react-overlay-scrollbars-smooth/actions/workflows/ci.yml/badge.svg)](https://github.com/kwooshung/react-overlay-scrollbars-smooth/actions/)\n[![codecov](https://codecov.io/gh/kwooshung/react-overlay-scrollbars-smooth/graph/badge.svg?token=VVZJE7H0KD)](https://codecov.io/gh/kwooshung/react-overlay-scrollbars-smooth)\n[![Maintainability](https://api.codeclimate.com/v1/badges/325d0881b1ca19165d35/maintainability)](https://codeclimate.com/github/kwooshung/react-overlay-scrollbars-smooth/maintainability/)\n[![Gitee Repo](https://img.shields.io/badge/Gitee-react--overlay--scrollbars--smooth-165dff?logo=gitee)](https://gitee.com/kwooshung/react-overlay-scrollbars-smooth/)\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"README.md\" style=\"font-weight:700;color:#165dff;text-decoration:underline;\"\u003eEnglish\u003c/a\u003e | \n    \u003ca href=\"README.zh-CN.md\"\u003e中文\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n## Why Develop It?\n\n- I grew tired of the default browser scrollbars that look unappealing and vary across different browsers.\n- They failed to maintain a consistent appearance and behavior across various browsers and lacked deep customization options.\n- The default scrollbar doesn’t align with the design aesthetic of your website or application.\n- 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.\n- 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.\n- The scrollbar feels stiff and not smooth enough when using the mouse wheel to scroll.\n\n## Installation\n\n### npm\n\n```bash\nnpm install @kwooshung/react-overlay-scrollbars-smooth\n```\n\n### yarn\n\n```bash\nyarn add @kwooshung/react-overlay-scrollbars-smooth\n```\n\n### pnpm\n\n```bash\npnpm add @kwooshung/react-overlay-scrollbars-smooth\n```\n\n## Usage\n\n### Styles\n\nIn some frameworks, you can directly introduce styles in global `css` / `less` / `scss`, as shown below:\n\n```css\n@import url('@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css');\n```\n\nIn some frameworks, such as `Next.js`, you may need to add the `~` character, as shown below:\n\n```css\n@import url('~@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css');\n```\n\nYou can also introduce it in a global page, such as the `Layout` page in `Next.js` or the corresponding component, as shown below:\n\n```tsx\nimport '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';\n```\n\n### components\n\nUse the `OverlayScrollbarsSmooth` component on an element as follows:\n\n```tsx\nimport { OverlayScrollbarsSmooth } from '@kwooshung/react-overlay-scrollbars-smooth';\n\n// What is used here is to introduce secondary styles directly into the component. You can also use other methods above.\nimport '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';\n\nfunction App() {\n  return (\n    \u003cdiv style={{ height: '300px' }}\u003e\n      \u003cOverlayScrollbarsSmooth\u003e\n        \u003cdiv style={{ height: '1000px' }} /\u003e\n      \u003c/OverlayScrollbarsSmooth\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nIf you want it to work on `Body`, you can do this:\n\n```tsx\nimport { OverlayScrollbarsSmooth } from '@kwooshung/react-overlay-scrollbars-smooth';\n\nfunction App() {\n  // 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!\n  return \u003cOverlayScrollbarsSmooth tag='body' /\u003e;\n}\n```\n\n### hooks\n\nYou 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:\n\n```tsx\nimport { OverlayScrollbarsSmooth, useSmoothScroll } from '@kwooshung/react-overlay-scrollbars-smooth';\nimport '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';\n\nfunction App() {\n  useSmoothScroll();\n\n  return (\n    \u003cdiv style={{ height: '300px' }}\u003e\n      \u003cOverlayScrollbarsSmooth\u003e\n        \u003cdiv style={{ height: '1000px' }} /\u003e\n      \u003c/OverlayScrollbarsSmooth\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n### API\n\n#### OverlayScrollbarsSmooth\n\nThe `OverlayScrollbarsSmooth` component supports all `OverlayScrollbars` APIs, you can view [OverlayScrollbars API](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react#properties) here.\n\n| Properties | Description                                                                                                                                           |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| tag        | `string`, default value: `div`, if it is: `body`, acts on `Body`, thus replacing the default scroll bar. `element` equivalent to `OverlayScrollbars`; |\n| className  | `string`, default value: `''`, custom class name; invalid when `tag`=`body`;                                                                          |\n| options    | Equivalent to `options` of `OverlayScrollbars`, default: `{scrollbars: {theme: 'os-theme-dark'}}`                                                     |\n| events     | Equivalent to `events` of `OverlayScrollbars`, default: `{}`                                                                                          |\n\n#### useSmoothScroll\n\nSupports 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\n\n```tsx\nimport { OverlayScrollbarsSmooth, useSmoothScroll } from '@kwooshung/react-overlay-scrollbars-smooth';\nimport '@kwooshung/react-overlay-scrollbars-smooth/dist/react-overlay-scrollbars-smooth.css';\n\nfunction App() {\n  useSmoothScroll({\n    // Scrolling Core\n    frameRate: 150, // [ms]\n    animationTime: 1000, // [ms]\n    stepSize: 100, // [px]\n\n    // Pulse (less tweakable)\n    // ratio of \"tail\" to \"acceleration\"\n    pulseAlgorithm: true,\n    pulseScale: 4,\n    pulseNormalize: true,\n\n    // Acceleration\n    accelerationDelta: 50,\n    accelerationMax: 3,\n\n    // Keyboard Settings\n    keyboardSupport: true,\n    arrowScroll: 50,\n\n    // Other\n    touchpadSupport: false, // ignore touchpad by default\n    fixedBackground: true\n  });\n\n  return (\n    \u003cdiv style={{ height: '300px' }}\u003e\n      \u003cOverlayScrollbarsSmooth\u003e\n        \u003cdiv style={{ height: '1000px' }} /\u003e\n      \u003c/OverlayScrollbarsSmooth\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Open source projects used\n\n\u003e Thanks to the project authors for their selfless contributions to the open source community, making our work easier! ! !\n\n- [OverlayScrollbars：Excellent scroll bar custom component](https://github.com/KingSora/OverlayScrollbars/)\n- [smoothscroll-for-websites：Excellent scroll bar smoothing script](https://github.com/gblazex/smoothscroll-for-websites)\n\n## LICENSE\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwooshung%2Freact-overlay-scrollbars-smooth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkwooshung%2Freact-overlay-scrollbars-smooth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwooshung%2Freact-overlay-scrollbars-smooth/lists"}