gemini-scrollbar

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

There is a React wrapper too — 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

npm i gemini-scrollbar --save

Bower

bower install gemini-scrollbar --save

Usage

JS

var GeminiScrollbar = require('gemini-scrollbar')

var myScrollbar = new GeminiScrollbar({
    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.

<link href="<path-to-gemini-scrollbar>/gemini-scrollbar.css" rel="stylesheet">
<script src="<path-to-gemini-scrollbar>/index.js"></script>

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:

/* 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 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.
• 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:

    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:

    <!-- (createElements: false) example markup -->
  
    <div class="something-scrollable">
      <div class="gm-scrollbar -vertical">
        <div class="thumb"></div>
      </div>
      <div class="gm-scrollbar -horizontal">
        <div class="thumb"></div>
      </div>
      <div class="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 option on this commit.

Related

• react-gemini-scrollbar - React wrapper

License

MIT © Noel Delgado

1.5.3 (2017-10-18)

• #56 avoid stop propagation

1.5.2 (2017-08-01)

• #53 prevent losing keyboard focus in object

1.5.1 (2017-05-18)

• #47 hide thumb when no more scroll needed
• #49 hovering parent container reveals child container scrollbars

1.5.0 (2017-03-05)

Feature:

• #41 add minThumbSize option, defaults to 20 (px)

1.4.3 (2016-07-26)

Patch:

• #31 removed reset of viewElement.style.{width,height}, turn off relayouts on update.

1.4.2 (2016-06-23)

Bugfixes:

• comment
  • Removed visibility: hidden from .gm-resize-trigger so it works on Firefox.
  • Updated the order in how we add the type for the resizer object so it works on IE correctly.

1.4.1 (2016-06-8)

Bugfixes:

• #29 .gm-resize-trigger causes white block overlaying scrollable content
• #23 fix autoshow functionality whilst dragging thumb of a scrollbar

1.4.0 (2016-05-28)

Features:

• #26 Add a handler to detect resizes of the scrolling element.
• Added onResize option hook by which clients can be notified of resize events

1.3.2 (2016-02-17)

Bugfixes:

• 3b5674c Remove scrollbar width test element.
• Clear viewElement{width,height} before reading them back on the update method.

1.3.1 (2016-01-11)

Bugfixes:

• added inline styles to the test element
• removed .gm-test css rule from the stylesheet

1.3.0 (2015-11-19)

Features:

• #16 Allow user to force Gemini

1.2.9 (2015-08-17)

Bugfixes:

• #11 Classnames don’t get added to the elements

1.2.8 (2015-07-18)

Bugfixes:

• do not remove class selectors if the markup is already defined (createElements: false)

1.2.7 (2015-06-28)

Bugfixes:

• do not re-append elements on create if createElements option is false
• do not add gm-prevented after destroy
• clean document and window references on destroy for reateElements: false

1.2.6 (2015-06-23)

Bugfixes:

• #9 better support for scrollbars with offset positions

1.2.5 (2015-06-21)

Bugfixes:

• #7 do not remove elements when calling the destroy method if the createElements option was set to false

1.2.4 (2015-05-13)

Bugfixes:

• getViewElement method returning null if the scroll bars were not created

1.2.3 (2015-04-29)

Features:

• Added getViewElement method that returns the scrollable element, useful if you want check its properties such as scrollHeight or add/remove content

1.1.3 (2015-04-08)

Bugfixes:

• OS X: showing custom scrollbars even when having overlayed ones natively #1
• Prevent error when loading the script on the head :/ #2

1.1.2 (2015-04-06)

Features:

• Safari support
  • added webkitTranslate for thumb position change

1.0.2 (2015-03-29)

Features:

• IE9 support

  • classList || className (add/remove class selectors)
  • style.transform || style.msTransform (update thumb position)
  • document.onstartselection prevented while draggin' the scrollbars

• Minor Bugfixes:

• :active state === :hover state by default for .ms-scrollbar .thumb

• thumb inherit border-radius from parent ms-scrollbar by default

1.0.1 (2015-03-28)

Bugfixes:

• SCROLLBAR_WIDTH value when ::-webkit-scrollbar was present with an explicit width
• Force hiding the scrollbar elements when the custom-scrollbars were prevented

1.0.0 (2015-03-27)

Updates:

• :after pseudo element is not longer used to style the scrollbars. This makes the process of customization much more intuitive