{"id":13907298,"url":"https://github.com/noeldelgado/gemini-scrollbar","last_synced_at":"2025-05-16T08:06:24.266Z","repository":{"id":28538426,"uuid":"32055422","full_name":"noeldelgado/gemini-scrollbar","owner":"noeldelgado","description":":first_quarter_moon: Custom overlay-scrollbars with native scrolling mechanism for web applications","archived":false,"fork":false,"pushed_at":"2023-12-13T07:13:24.000Z","size":711,"stargazers_count":427,"open_issues_count":23,"forks_count":63,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-08T21:07:09.621Z","etag":null,"topics":["custom-scrollbar","custom-scrollbars","gemini-scrollbar","javascript","js-library","native-scrollbars","overlay-scrollbars","scrollbars"],"latest_commit_sha":null,"homepage":"https://noeldelgado.github.io/gemini-scrollbar/","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/noeldelgado.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-12T03:40:52.000Z","updated_at":"2025-04-19T07:11:18.000Z","dependencies_parsed_at":"2024-06-18T12:40:20.436Z","dependency_job_id":"86fc188c-f1e6-4552-9a74-a7516ad4b69e","html_url":"https://github.com/noeldelgado/gemini-scrollbar","commit_stats":{"total_commits":104,"total_committers":9,"mean_commits":"11.555555555555555","dds":0.09615384615384615,"last_synced_commit":"9298ea8c927287cfc184eb2772dd2dee47989bfd"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fgemini-scrollbar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fgemini-scrollbar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fgemini-scrollbar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fgemini-scrollbar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noeldelgado","download_url":"https://codeload.github.com/noeldelgado/gemini-scrollbar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["custom-scrollbar","custom-scrollbars","gemini-scrollbar","javascript","js-library","native-scrollbars","overlay-scrollbars","scrollbars"],"created_at":"2024-08-06T23:01:52.705Z","updated_at":"2025-05-16T08:06:19.257Z","avatar_url":"https://github.com/noeldelgado.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# gemini-scrollbar\n\n[![npm-image](https://img.shields.io/npm/v/gemini-scrollbar.svg)](https://www.npmjs.com/package/gemini-scrollbar)\n![bower-image](https://img.shields.io/bower/v/gemini-scrollbar.svg)\n![license-image](https://img.shields.io/npm/l/gemini-scrollbar.svg)\n[![Known Vulnerabilities](https://snyk.io/test/npm/gemini-scrollbar/badge.svg)](https://snyk.io/test/npm/gemini-scrollbar)\n[![Dependencies](https://img.shields.io/david/noeldelgado/gemini-scrollbar.svg)](https://david-dm.org/noeldelgado/gemini-scrollbar)\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/noeldelgado/gemini-scrollbar.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/noeldelgado/gemini-scrollbar/alerts/)\n[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/noeldelgado/gemini-scrollbar.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/noeldelgado/gemini-scrollbar/context:javascript)\n\nCustom overlay-scrollbars with native scrolling mechanism for web applications (if needed).\n\n*There is a __React__ wrapper too — [react-gemini-scrollbar](https://github.com/noeldelgado/react-gemini-scrollbar).*\n\n###### Problem Description\n\nNowadays, some OS’s provides “overlay-scrollbars” natively. Those scrollbars look nice and work well (mostly mobile browsers and OSX opt-in). The problem came when you have to customize the remaining ‘ugly’ scrollbars out there. e.g: “*having a sidebar with a dark background + native-__non-floating__-scrollbars*” ...hum, ugly. Even when this problem can be merely visual, for me is a way of enhancing the user experience.\n\n###### Constraints\n\n- Fallbacks to use the native scrollbars when the OS/browser supports “overlay-scrollbars”.\n- Mimics the scrollbar behaviour when replaced with the custom ones (click, drag...).\n- IE9+ support.\n\n###### Solution Proposal\n\nCheck the scrollbar size. If the scrollbar size is zero (which means the scrollbars are already “over the content”) then we **do nothing**. Otherwise we simply “hide” native scrollbar and show custom in its place.\n\n## Demo\n\nhttps://noeldelgado.github.io/gemini-scrollbar/\n\n## Dependencies\nNone\n\n## Installation\n\n**NPM**\n\n```sh\nnpm i gemini-scrollbar --save\n```\n\n**Bower**\n\n```sh\nbower install gemini-scrollbar --save\n```\n\n## Usage\n\n**JS**\n\n```js\nvar GeminiScrollbar = require('gemini-scrollbar')\n\nvar myScrollbar = new GeminiScrollbar({\n    element: document.querySelector('.my-scrollbar')\n}).create();\n```\n\n**LESS**\n\n```less\n@import (inline) \"\u003cpath-to-gemini-scrollbar\u003e/gemini-scrollbar.css\";\n```\n\n**CSS**\n\n```css\n@import url(\u003cpath-to-gemini-scrollbar\u003e/gemini-scrollbar.css);\n```\n\nOr, you can add the relevant files in your document.\n\n```html\n\u003clink href=\"\u003cpath-to-gemini-scrollbar\u003e/gemini-scrollbar.css\" rel=\"stylesheet\"\u003e\n\u003cscript src=\"\u003cpath-to-gemini-scrollbar\u003e/index.js\"\u003e\u003c/script\u003e\n```\n\n## Options\n\nname | type | default | description\n|:--- | :--- | :--- | :---\n**element \u0026ast;** | HTMLElement | `null` | The element to apply scrollbars\nautoshow | Boolean | `false` | Show scrollbars upon hovering\ncreateElements | Boolean | `true` | Create and append the require HTMLElements at runtime.\nforceGemini | Boolean | `false` | Force Gemini scrollbars even if native overlay-scrollbars are available. Useful for development.\nonResize | Function | `null` | Hook by which clients can be notified of resize events.\nminThumbSize | Number `(px)` | `20` | Sets the minimum size of the thumbs.\n\n\\* `required`\n\n## Basic Methods\n\nname | description\n|:--- | :---\ncreate | Bind the events, create the required elements and display the scrollbars.\nupdate | Recalculate the viewbox and scrollbar dimensions.\ndestroy | Unbind the events and remove the custom scrollbar elements.\n\n## Other Mehods\n\nname | description\n|:-- | :--\ngetViewElement | Returns the scrollable element\n\n## Customization\n\nYou can change the styles of the scrollbars using CSS. e.g:\n\n```css\n/* override gemini-scrollbar default styles */\n\n/* vertical scrollbar track */\n.gm-scrollbar.-vertical {\n  background-color: #f0f0f0\n}\n\n/* horizontal scrollbar track */\n.gm-scrollbar.-horizontal {\n  background-color: transparent;\n}\n\n/* scrollbar thumb */\n.gm-scrollbar .thumb {\n  background-color: rebeccapurple;\n}\n.gm-scrollbar .thumb:hover {\n  background-color: fuchsia;\n}\n```\n\n## Notes\n\n- **native overlay-scrollbar:** We check the scrollbar size [using this approach](http://davidwalsh.name/detect-scrollbar-width) by David Walsh. If the scrollbar size is zero (which means the scrollbars are “over the content”) then we do nothing but add the `gm-prevented` class selector to the element, which contains the non-standard `-webkit-overflow-scrolling: touch;` declaration for web devices to use momentum-based scrolling. No event binding, element creation... nothing, in this case, we leave the OS/browser do its job. Why? you already have nice looking scrollbars for free.\n- **::-webkit-scrollbar:** If you plan to use gemini-scrollbar on your application I highly recommend you removing any Webkit scrollbar styles you may have, why? using the `-webkit-` prefixed pseudo-elements will cause Webkit turning off its built-in scrollbar rendering, interfering with our scrollbar-size-check. You can read a bit more about this issue on [this commit](../../issues/1).\n- **create method:** The custom scrollbars will **not** render until you call the `create` method on the instance. i.e: `myScrollbar.create();`\n- **required height:** To avoid unexpected results, it is recommended that you specify the `height` property with a value to the element you applying the custom scrollbars (or to its parent).\n- **body tag:** If you want to apply custom scrollbars to `body`, make sure to declare a `height` value either to the `:root` pseudo-class or to the `html` element. e.g:\n\n    ```css\n    html {\n        height: 100%;\n        /* or */\n        height: 100vh;\n        overflow: hidden;\n    }\n    ```\n- **createElements option:** The `createElements` option specify wheater or not gemini-scrollbar should create and append the require HTMLElements at runtime. Its default value is `true`. Passing this option as `false` will assume that you to have added the required markup with the specific CSS class selectors on them for it to work. i.e:\n\n    ```html\n    \u003c!-- (createElements: false) example markup --\u003e\n\n    \u003cdiv class=\"something-scrollable\"\u003e\n      \u003cdiv class=\"gm-scrollbar -vertical\"\u003e\n        \u003cdiv class=\"thumb\"\u003e\u003c/div\u003e\n      \u003c/div\u003e\n      \u003cdiv class=\"gm-scrollbar -horizontal\"\u003e\n        \u003cdiv class=\"thumb\"\u003e\u003c/div\u003e\n      \u003c/div\u003e\n      \u003cdiv class=\"gm-scroll-view\"\u003e\n        All your content goes here.\n      \u003c/div\u003e\n    \u003c/div\u003e\n    ```\n\nThis way you can be sure the library will not touch/change your nodes structure. You can read more about the reason of this option [on this commit](https://github.com/noeldelgado/gemini-scrollbar/commit/2bb73c82f9d1588fb267fba08518adfe1170885c).\n\n## Related\n\n- [react-gemini-scrollbar](https://github.com/noeldelgado/react-gemini-scrollbar) - React wrapper\n\n## License\nMIT © [Noel Delgado](http://pixelia.me/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoeldelgado%2Fgemini-scrollbar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoeldelgado%2Fgemini-scrollbar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoeldelgado%2Fgemini-scrollbar/lists"}