# gemini-scrollbar > Custom scrollbars with native scrolling Latest version **1.5.3** (published 2017-10-19) · MIT license · 0 weekly downloads ## Install ```sh npm install gemini-scrollbar pnpm add gemini-scrollbar yarn add gemini-scrollbar bun add gemini-scrollbar ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.5.3 | | Published | 2017-10-19 | | First published | 2015-03-13 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 429 | | Author | Noel Delgado | | Maintainers | noeldelgado | | Keywords | native, scrolling, skinnable, custom, scrollbar, scrollbars, scroll, mousewheel, trackpad, smooth-scroll | ## Links - npm: https://www.npmjs.com/package/gemini-scrollbar - Repository: https://github.com/noeldelgado/gemini-scrollbar - Issues: https://github.com/noeldelgado/gemini-scrollbar/issues - npm.io page: https://npm.io/package/gemini-scrollbar ## Alternatives - [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads - [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads - [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads - [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads - [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads ## Recent versions - 1.5.3 (latest) — 2017-10-19 - 1.5.2 — 2017-08-02 - 1.5.1 — 2017-05-18 - 1.5.0 — 2017-03-06 - 1.4.3 — 2016-07-26 - 1.4.2 — 2016-06-24 - 1.4.1 — 2016-06-09 - 1.4.0 — 2016-05-28 - 1.3.2 — 2016-02-17 - 1.3.1 — 2016-01-12 - 1.3.0 — 2015-11-19 - 1.2.9 — 2015-08-18 - 1.2.8 — 2015-07-19 - 1.2.7 — 2015-06-29 - 1.2.6 — 2015-06-23 - … 11 more at https://npm.io/package/gemini-scrollbar/versions ## README # gemini-scrollbar [![npm-image](https://img.shields.io/npm/v/gemini-scrollbar.svg)](https://www.npmjs.com/package/gemini-scrollbar) ![bower-image](https://img.shields.io/bower/v/gemini-scrollbar.svg) ![license-image](https://img.shields.io/npm/l/gemini-scrollbar.svg) Custom overlay-scrollbars with native scrolling mechanism for web applications (if needed). *There is a __React__ wrapper too — [react-gemini-scrollbar](https://github.com/noeldelgado/react-gemini-scrollbar).* ###### Problem Description Nowadays, 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. ###### Constraints - Fallbacks to use the native scrollbars when the OS/browser supports “overlay-scrollbars”. - Mimics the scrollbar behaviour when replaced with the custom ones (click, drag...). - IE9+ support. ###### Solution Proposal Check 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. ## Demo https://noeldelgado.github.io/gemini-scrollbar/ ## Dependencies None ## Installation **NPM** ```sh npm i gemini-scrollbar --save ``` **Bower** ```sh bower install gemini-scrollbar --save ``` ## Usage **JS** ```js var GeminiScrollbar = require('gemini-scrollbar') var myScrollbar = new GeminiScrollbar({ element: document.querySelector('.my-scrollbar') }).create(); ``` **LESS** ```less @import (inline) "/gemini-scrollbar.css"; ``` **CSS** ```css @import url(/gemini-scrollbar.css); ``` Or, you can add the relevant files in your document. ```html ``` ## Options name | type | default | description |:--- | :--- | :--- | :--- **element *** | HTMLElement | `null` | The element to apply scrollbars autoshow | Boolean | `false` | Show scrollbars upon hovering createElements | Boolean | `true` | Create and append the require HTMLElements at runtime. forceGemini | Boolean | `false` | Force Gemini scrollbars even if native overlay-scrollbars are available. Useful for development. onResize | Function | `null` | Hook by which clients can be notified of resize events. minThumbSize | Number `(px)` | `20` | Sets the minimum size of the thumbs. \* `required` ## Basic Methods name | description |:--- | :--- create | Bind the events, create the required elements and display the scrollbars. update | Recalculate the viewbox and scrollbar dimensions. destroy | Unbind the events and remove the custom scrollbar elements. ## Other Mehods name | description |:-- | :-- getViewElement | Returns the scrollable element ## Customization You can change the styles of the scrollbars using CSS. e.g: ```css /* override gemini-scrollbar default styles */ /* vertical scrollbar track */ .gm-scrollbar.-vertical { background-color: #f0f0f0 } /* horizontal scrollbar track */ .gm-scrollbar.-horizontal { background-color: transparent; } /* scrollbar thumb */ .gm-scrollbar .thumb { background-color: rebeccapurple; } .gm-scrollbar .thumb:hover { background-color: fuchsia; } ``` ## Notes - **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. - **::-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). - **create method:** The custom scrollbars will **not** render until you call the `create` method on the instance. i.e: `myScrollbar.create();` - **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). - **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: ```css html { height: 100%; /* or */ height: 100vh; overflow: hidden; } ``` - **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: ```html
All your content goes here.
``` This 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). ## Related - [react-gemini-scrollbar](https://github.com/noeldelgado/react-gemini-scrollbar) - React wrapper ## License MIT © [Noel Delgado](http://pixelia.me/) --- _Source: https://npm.io/package/gemini-scrollbar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._