Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

:first_quarter_moon: Custom overlay-scrollbars with native scrolling mechanism for web applications
https://github.com/noeldelgado/gemini-scrollbar

custom-scrollbar custom-scrollbars gemini-scrollbar javascript js-library native-scrollbars overlay-scrollbars scrollbars

Last synced: about 1 month ago
JSON representation

:first_quarter_moon: Custom overlay-scrollbars with native scrolling mechanism for web applications

Host: GitHub
URL: https://github.com/noeldelgado/gemini-scrollbar
Owner: noeldelgado
License: mit
Created: 2015-03-12T03:40:52.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2023-12-13T07:13:24.000Z (9 months ago)
Last Synced: 2024-05-18T19:45:18.834Z (4 months ago)
Topics: custom-scrollbar, custom-scrollbars, gemini-scrollbar, javascript, js-library, native-scrollbars, overlay-scrollbars, scrollbars
Language: JavaScript
Homepage: https://noeldelgado.github.io/gemini-scrollbar/
Size: 694 KB
Stars: 426
Watchers: 13
Forks: 62
Open Issues: 23
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Authors: AUTHORS

Awesome Lists containing this project

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)

[![Known Vulnerabilities](https://snyk.io/test/npm/gemini-scrollbar/badge.svg)](https://snyk.io/test/npm/gemini-scrollbar)

[![Dependencies](https://img.shields.io/david/noeldelgado/gemini-scrollbar.svg)](https://david-dm.org/noeldelgado/gemini-scrollbar)

[![Total alerts](https://img.shields.io/lgtm/alerts/g/noeldelgado/gemini-scrollbar.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/noeldelgado/gemini-scrollbar/alerts/)

[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/noeldelgado/gemini-scrollbar.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/noeldelgado/gemini-scrollbar/context:javascript)

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 &ast;** | 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/)