Repository files navigation

Custom overlay-scrollbars with native scrolling mechanism for web applications (if needed).

There is aReact wrapper too —react-gemini-scrollbar.

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.

• 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.

Check the scrollbar size. If the scrollbar size is zero (which means the scrollbars are already “over the content”) then wedo nothing. Otherwise we simply “hide” native scrollbar and show custom in its place.

https://noeldelgado.github.io/gemini-scrollbar/

None

NPM

npm i gemini-scrollbar --save

Bower

bower install gemini-scrollbar --save

JS

varGeminiScrollbar=require('gemini-scrollbar')varmyScrollbar=newGeminiScrollbar({element:document.querySelector('.my-scrollbar')}).create();

LESS

@import (inline)"<path-to-gemini-scrollbar>/gemini-scrollbar.css";

CSS

@import url(<path-to-gemini-scrollbar>/gemini-scrollbar.css);

Or, you can add the relevant files in your document.

<linkhref="<path-to-gemini-scrollbar>/gemini-scrollbar.css"rel="stylesheet"><scriptsrc="<path-to-gemini-scrollbar>/index.js"></script>

*required

You can change the styles of the scrollbars using CSS. e.g:

/* 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;}

• native overlay-scrollbar: We check the scrollbar sizeusing this approach by David Walsh. If the scrollbar size is zero (which means the scrollbars are “over the content”) then we do nothing but add thegm-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 onthis commit.

• create method: The custom scrollbars willnot render until you call thecreate method on the instance. i.e:myScrollbar.create();

• required height: To avoid unexpected results, it is recommended that you specify theheight 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 tobody, make sure to declare aheight value either to the:root pseudo-class or to thehtml element. e.g:

  html {height:100%;/* or */height:100vh;overflow: hidden;}

• createElements option: ThecreateElements option specify wheater or not gemini-scrollbar should create and append the require HTMLElements at runtime. Its default value istrue. Passing this option asfalse will assume that you to have added the required markup with the specific CSS class selectors on them for it to work. i.e:

  <!-- (createElements: false) example markup --><divclass="something-scrollable"><divclass="gm-scrollbar -vertical"><divclass="thumb"></div></div><divclass="gm-scrollbar -horizontal"><divclass="thumb"></div></div><divclass="gm-scroll-view">    All your content goes here.</div></div>

This way you can be sure the library will not touch/change your nodes structure. You can read more about the reason of this optionon this commit.

• react-gemini-scrollbar - React wrapper

MIT ©Noel Delgado