gemini-scrollbar - GitLite

KO | EN

gitlite — search

#javascript #typescript #llm #go #android #machine-learning #macos #windows #awesome #cli #kubernetes #pytorch #ios #openai

gemini-scrollbar

(★ 429)

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

File Explorer

Download Latest Version (.zip)

- 00-sidebar.html
- 01-body.html
- 03-grid.html
- 04-random-tests.html
- 05-destroy.html
- update-authors.sh
.gitignore
AUTHORS
bower.json
CHANGELOG.md
CONTRIBUTING.md
gemini-scrollbar.css
index.js
lgtm.yml
LICENSE
package.json
README.md

# Installation Guide

1. Get the code

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

Downloads the entire project code from GitHub to your computer.

cd gemini-scrollbar

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm i gemini-scrollbar --save

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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) "<path-to-gemini-scrollbar>/gemini-scrollbar.css";
```

**CSS**

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

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

```html
<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 &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

<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](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/)