mirrors/OverlayScrollbars
2
0
Fork 0
mirror of https://github.com/tenrok/OverlayScrollbars.git synced 2026-05-17 03:09:39 +03:00
Code Issues Packages Projects Releases Wiki Activity

improve documentation

Browse Source
This commit is contained in:
Rene Haas
2023-03-09 00:48:19 +01:00
parent 0259b7ef58
commit 1b7230750b
9 changed files with 115 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+10 -8
View File
@@ -22,18 +22,19 @@
I created this plugin because I hate ugly and space consuming scrollbars. Similar plugins haven't met my requirements in terms of features, quality, simplicity, license or browser support.
## Goals & Features
## Goals & Features.es6
- Simple, powerful and well documented API
- High browser compatibility - <b>Firefox 59+</b>, <b>Chrome 55+</b>, <b>Opera 42+</b>, <b>Edge 12+</b>, <b>Safari 10+</b> and <b>IE 11</b>
- Can be run on the server - <b>SSR</b>, <b>SSG</b> and <b>ISR</b> support
- Tested on various devices - <b>Mobile</b>, <b>Desktop</b> and <b>Tablet</b>
- Tested with various (and mixed) inputs - <b>Mouse</b>, <b>touch</b> and <b>pen</b>
- <b>Treeshaking</b> - bundle only what you really need
- Automatic update detection - <b>no polling</b>
- Usage of latest browser features - best <b>performance</b> in new browsers
- High browser compatibility - **Firefox 59+**, **Chrome 55+**, **Opera 42+**, **Edge 12+**, **Safari 10+** and **IE 11**
- Can be run on the server - **SSR**, **SSG** and **ISR** support
- Tested on various devices - **Mobile**, **Desktop** and **Tablet**
- Tested with various (and mixed) inputs - **Mouse**, **touch** and **pen**
- **Treeshaking** - bundle only what you really need
- Automatic update detection - **no polling**
- Usage of latest browser features - best **performance** in new browsers
- Bidirectional - LTR or RTL direction support
- Supports usage on the `body` element
- Supports all **virtual scrolling** libraries
- Simple and effective scrollbar styling
- Highly customizable
- TypeScript support - fully written in TypeScript
@@ -53,6 +54,7 @@ Additionally to the vanilla JavaScript version you can use the official framewor
## Getting started
### npm & nodejs
OverlayScrollbars can be downloaded from [npm](https://www.npmjs.com/package/overlayscrollbars) or the package manager of your choice:
```sh
npm install overlayscrollbars
docs/404.html
+2 -2
View File
@@ -1,4 +1,4 @@
<!DOCTYPE html><html lang="en" data-overlayscrollbars-initialize=""><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><meta name="description" content="A javascript scrollbar plugin that hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling."/><link rel="icon" href="/OverlayScrollbars/_next/static/media/favicon.7b344e85.ico"/><link rel="shortcut icon" type="image/x-icon" href="/OverlayScrollbars/_next/static/media/favicon.7b344e85.ico"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><meta name="theme-color" content="#36befd"/><meta name="msapplication-TileColor" content="#36befd"/><meta name="msapplication-navbutton-color" content="#36befd"/><meta name="application-name" content="OverlayScrollbars"/><meta name="msapplication-tooltip" content="OverlayScrollbars"/><meta name="apple-mobile-web-app-title" content="OverlayScrollbars"/><script type="application/ld+json">{"@context":"http://schema.org","@type":"SoftwareSourceCode","url":"https://kingsora.github.io/OverlayScrollbars","name":"OverlayScrollbars","description":"A javascript scrollbar plugin that hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling.","license":"https://en.wikipedia.org/wiki/MIT_License","keywords":"js,javascript,typescript,overlayscrollbars,overlay,scrollbars,custom,scrollbar,plugin,react,vue,angular,treeshaking","isAccessibleForFree":true,"image":"https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/logo/logo.png","codeRepository":"https://github.com/KingSora/OverlayScrollbars","runtimePlatform":"browser","maintainer":{"@type":"Person","name":"Rene Haas","additionalName":"KingSora","url":"https://github.com/KingSora"},"programmingLanguage":{"@type":"ComputerLanguage","name":"javascript","alternateName":"js"}}</script><title>404: This page could not be found</title><meta name="next-head-count" content="14"/><link rel="preload" href="/OverlayScrollbars/_next/static/css/2edffb4e954af5a3.css" as="style"/><link rel="stylesheet" href="/OverlayScrollbars/_next/static/css/2edffb4e954af5a3.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/OverlayScrollbars/_next/static/chunks/polyfills-c67a75d1b6f99dc8.js"></script><script src="/OverlayScrollbars/_next/static/chunks/webpack-dd4523633be5c384.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/framework-80c43e603d70cda7.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/main-ea1211b077f8a1ed.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/pages/_app-5ce28d8f4b54a7a6.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/pages/_error-fa37e1d4331cc885.js" defer=""></script><script src="/OverlayScrollbars/_next/static/RedqsvCUdhwuhIGeiNRlP/_buildManifest.js" defer=""></script><script src="/OverlayScrollbars/_next/static/RedqsvCUdhwuhIGeiNRlP/_ssgManifest.js" defer=""></script></head><body data-overlayscrollbars-initialize=""><div id="__next"><div class="font-sans font-normal text-primary-dark"><div style="font-family:-apple-system, BlinkMacSystemFont, Roboto, &quot;Segoe UI&quot;, &quot;Fira Sans&quot;, Avenir, &quot;Helvetica Neue&quot;, &quot;Lucida Grande&quot;, sans-serif;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div><style>
<!DOCTYPE html><html lang="en" data-overlayscrollbars-initialize=""><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><meta name="description" content="A javascript scrollbar plugin that hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling."/><link rel="icon" href="/OverlayScrollbars/_next/static/media/favicon.7b344e85.ico"/><link rel="shortcut icon" type="image/x-icon" href="/OverlayScrollbars/_next/static/media/favicon.7b344e85.ico"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><meta name="theme-color" content="#36befd"/><meta name="msapplication-TileColor" content="#36befd"/><meta name="msapplication-navbutton-color" content="#36befd"/><meta name="application-name" content="OverlayScrollbars"/><meta name="msapplication-tooltip" content="OverlayScrollbars"/><meta name="apple-mobile-web-app-title" content="OverlayScrollbars"/><script type="application/ld+json">{"@context":"http://schema.org","@type":"SoftwareSourceCode","url":"https://kingsora.github.io/OverlayScrollbars","name":"OverlayScrollbars","description":"A javascript scrollbar plugin that hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling.","license":"https://en.wikipedia.org/wiki/MIT_License","keywords":"js,javascript,typescript,overlayscrollbars,overlay,scrollbars,custom,scrollbar,plugin,react,vue,angular,treeshaking","isAccessibleForFree":true,"image":"https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/logo/logo.png","codeRepository":"https://github.com/KingSora/OverlayScrollbars","runtimePlatform":"browser","maintainer":{"@type":"Person","name":"Rene Haas","additionalName":"KingSora","url":"https://github.com/KingSora"},"programmingLanguage":{"@type":"ComputerLanguage","name":"javascript","alternateName":"js"}}</script><title>404: This page could not be found</title><meta name="next-head-count" content="14"/><link rel="preload" href="/OverlayScrollbars/_next/static/css/2edffb4e954af5a3.css" as="style"/><link rel="stylesheet" href="/OverlayScrollbars/_next/static/css/2edffb4e954af5a3.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/OverlayScrollbars/_next/static/chunks/polyfills-c67a75d1b6f99dc8.js"></script><script src="/OverlayScrollbars/_next/static/chunks/webpack-dd4523633be5c384.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/framework-80c43e603d70cda7.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/main-ea1211b077f8a1ed.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/pages/_app-5ce28d8f4b54a7a6.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/pages/_error-fa37e1d4331cc885.js" defer=""></script><script src="/OverlayScrollbars/_next/static/MyU_DR0NDL6t-x0Gm3Atx/_buildManifest.js" defer=""></script><script src="/OverlayScrollbars/_next/static/MyU_DR0NDL6t-x0Gm3Atx/_ssgManifest.js" defer=""></script></head><body data-overlayscrollbars-initialize=""><div id="__next"><div class="font-sans font-normal text-primary-dark"><div style="font-family:-apple-system, BlinkMacSystemFont, Roboto, &quot;Segoe UI&quot;, &quot;Fira Sans&quot;, Avenir, &quot;Helvetica Neue&quot;, &quot;Lucida Grande&quot;, sans-serif;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div><style>
body { margin: 0; color: #000; background: #fff; }
.next-error-h1 {
border-right: 1px solid rgba(0, 0, 0, .3);
@@ -9,4 +9,4 @@
.next-error-h1 {
border-right: 1px solid rgba(255, 255, 255, .3);
}
}</style><h1 class="next-error-h1" style="display:inline-block;margin:0;margin-right:20px;padding:0 23px 0 0;font-size:24px;font-weight:500;vertical-align:top;line-height:49px">404</h1><div style="display:inline-block;text-align:left;line-height:49px;height:49px;vertical-align:middle"><h2 style="font-size:14px;font-weight:normal;line-height:49px;margin:0;padding:0">This page could not be found<!-- -->.</h2></div></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"RedqsvCUdhwuhIGeiNRlP","assetPrefix":"/OverlayScrollbars","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>
}</style><h1 class="next-error-h1" style="display:inline-block;margin:0;margin-right:20px;padding:0 23px 0 0;font-size:24px;font-weight:500;vertical-align:top;line-height:49px">404</h1><div style="display:inline-block;text-align:left;line-height:49px;height:49px;vertical-align:middle"><h2 style="font-size:14px;font-weight:normal;line-height:49px;margin:0;padding:0">This page could not be found<!-- -->.</h2></div></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"MyU_DR0NDL6t-x0Gm3Atx","assetPrefix":"/OverlayScrollbars","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>
docs/_next/static/RedqsvCUdhwuhIGeiNRlP/_buildManifest.js → docs/_next/static/MyU_DR0NDL6t-x0Gm3Atx/_buildManifest.js
+1 -1
View File
@@ -1 +1 @@
self.__BUILD_MANIFEST={__rewrites:{beforeFiles:[],afterFiles:[],fallback:[]},"/":["static/css/054cd89f2e050c9e.css","static/chunks/pages/index-c016a008b2f405c3.js"],"/_error":["static/chunks/pages/_error-fa37e1d4331cc885.js"],sortedPages:["/","/_app","/_error"]},self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();
self.__BUILD_MANIFEST={__rewrites:{beforeFiles:[],afterFiles:[],fallback:[]},"/":["static/css/054cd89f2e050c9e.css","static/chunks/pages/index-79d5f55dc79d656d.js"],"/_error":["static/chunks/pages/_error-fa37e1d4331cc885.js"],sortedPages:["/","/_app","/_error"]},self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();
docs/_next/static/RedqsvCUdhwuhIGeiNRlP/_ssgManifest.js → docs/_next/static/MyU_DR0NDL6t-x0Gm3Atx/_ssgManifest.js
View File
docs/_next/static/chunks/pages/index-79d5f55dc79d656d.js
+5
View File
File diff suppressed because one or more lines are too long
docs/_next/static/chunks/pages/index-c016a008b2f405c3.js
-5
View File
File diff suppressed because one or more lines are too long
docs/index.html
+41 -21
View File
File diff suppressed because one or more lines are too long
packages/overlayscrollbars/README.md
+10 -8
View File
@@ -22,18 +22,19 @@
I created this plugin because I hate ugly and space consuming scrollbars. Similar plugins haven't met my requirements in terms of features, quality, simplicity, license or browser support.
## Goals & Features
## Goals & Features.es6
- Simple, powerful and well documented API
- High browser compatibility - <b>Firefox 59+</b>, <b>Chrome 55+</b>, <b>Opera 42+</b>, <b>Edge 12+</b>, <b>Safari 10+</b> and <b>IE 11</b>
- Can be run on the server - <b>SSR</b>, <b>SSG</b> and <b>ISR</b> support
- Tested on various devices - <b>Mobile</b>, <b>Desktop</b> and <b>Tablet</b>
- Tested with various (and mixed) inputs - <b>Mouse</b>, <b>touch</b> and <b>pen</b>
- <b>Treeshaking</b> - bundle only what you really need
- Automatic update detection - <b>no polling</b>
- Usage of latest browser features - best <b>performance</b> in new browsers
- High browser compatibility - **Firefox 59+**, **Chrome 55+**, **Opera 42+**, **Edge 12+**, **Safari 10+** and **IE 11**
- Can be run on the server - **SSR**, **SSG** and **ISR** support
- Tested on various devices - **Mobile**, **Desktop** and **Tablet**
- Tested with various (and mixed) inputs - **Mouse**, **touch** and **pen**
- **Treeshaking** - bundle only what you really need
- Automatic update detection - **no polling**
- Usage of latest browser features - best **performance** in new browsers
- Bidirectional - LTR or RTL direction support
- Supports usage on the `body` element
- Supports all **virtual scrolling** libraries
- Simple and effective scrollbar styling
- Highly customizable
- TypeScript support - fully written in TypeScript
@@ -53,6 +54,7 @@ Additionally to the vanilla JavaScript version you can use the official framewor
## Getting started
### npm & nodejs
OverlayScrollbars can be downloaded from [npm](https://www.npmjs.com/package/overlayscrollbars) or the package manager of your choice:
```sh
npm install overlayscrollbars
website/src/components/index.mdx
+46 -24
View File
@@ -5,21 +5,22 @@ I created this plugin because I hate ugly and space consuming scrollbars. Simila
## Goals & Features
- Simple, powerful and well documented API
- High browser compatibility - <b>Firefox 59+</b>, <b>Chrome 55+</b>, <b>Opera 42+</b>, <b>Edge 12+</b>, <b>Safari 10+</b> and <b>IE 11</b>
- Can be run on the server - <b>SSR</b>, <b>SSG</b> and <b>ISR</b> support
- Tested on various devices - <b>Mobile</b>, <b>Desktop</b> and <b>Tablet</b>
- Tested with various (and mixed) inputs - <b>Mouse</b>, <b>touch</b> and <b>pen</b>
- <b>Treeshaking</b> - bundle only what you really need
- Automatic update detection - <b>no polling</b>
- Usage of latest browser features - best <b>performance</b> in new browsers
- High browser compatibility - **Firefox 59+**, **Chrome 55+**, **Opera 42+**, **Edge 12+**, **Safari 10+** and **IE 11**
- Can be run on the server - **SSR**, **SSG** and **ISR** support
- Tested on various devices - **Mobile**, **Desktop** and **Tablet**
- Tested with various (and mixed) inputs - **Mouse**, **touch** and **pen**
- **Treeshaking** - bundle only what you really need
- Automatic update detection - **no polling**
- Usage of latest browser features - best **performance** in new browsers
- Bidirectional - LTR or RTL direction support
- Supports usage on the `body` element
- Supports all **virtual scrolling** libraries
- Simple and effective scrollbar styling
- Highly customizable
- TypeScript support - fully written in TypeScript
- Dependency free - 100% self written to ensure small size and best functionality
- High quality and fully typed framework versions for [`react`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react), [`vue`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue), [`angular`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx), [`svelte`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-svelte) and [`solid`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-solid).
## Choose your framework
Additionally to the vanilla JavaScript version you can use the official framework components & utilities:
@@ -34,7 +35,8 @@ Additionally to the vanilla JavaScript version you can use the official framewor
## Getting started
### npm & node
### npm & nodejs
OverlayScrollbars can be downloaded from [npm](https://www.npmjs.com/package/overlayscrollbars) or the package manager of your choice:
```sh
npm install overlayscrollbars
@@ -42,39 +44,42 @@ npm install overlayscrollbars
After installation it can be imported:
```js
import 'overlayscrollbars/overlayscrollbars.css';
import { OverlayScrollbars } from 'overlayscrollbars';
import {
OverlayScrollbars,
ScrollbarsHidingPlugin,
SizeObserverPlugin,
ClickScrollPlugin
} from 'overlayscrollbars';
```
> __Note__: In older node versions use `'overlayscrollbars/styles/overlayscrollbars.css'` as the import path for the CSS file.
> __Note__: In older nodejs versions use `'overlayscrollbars/styles/overlayscrollbars.css'` as the import path for the CSS file.
### Manual download & embedding
<details>
<summary>
These instructions are for quick prototyping or old stacks. Click here to read them.
</summary>
<br />
You can use OverlayScrollbars without any bundler or package manager.
Simply download it from the [Releases](https://github.com/KingSora/OverlayScrollbars/releases) or use a [CDN](https://cdnjs.com/libraries/overlayscrollbars).
- Use the javascript files with the `.browser` extension.
- If you target old browsers use the `.es5` javascript file, for new browsers `.es6`.
- Use the javascript files with the `.es5` extension if you need to support older browsers like IE11, otherwise use the `.es6` files.
- For production use the javascript / stylesheet files with the `.min` extension.
Embedd OverlayScrollbars manually in your HTML:
```html
<link type="text/css" href="path/to/overlayscrollbars.css" rel="stylesheet" />
<script type="text/javascript" src="path/to/overlayscrollbars.js" defer></script>
<script type="text/javascript" src="path/to/overlayscrollbars.browser.es.js" defer></script>
```
You can use the global variable `OverlayScrollbarsGlobal` to access the api:
You can then use the global variable `OverlayScrollbarsGlobal` to access the api similar to how you can do it in nodejs / modules:
```js
var OverlayScrollbars = OverlayScrollbarsGlobal.OverlayScrollbars;
OverlayScrollbars(document.body, {});
var {
OverlayScrollbars,
ScrollbarsHidingPlugin,
SizeObserverPlugin,
ClickScrollPlugin
} = OverlayScrollbarsGlobal;
```
</details>
The examples in this documentation will use the `import` syntax instead of the `OverlayScrollbarsGlobal` object. Both versions are equivalent though.
## Initialization
@@ -507,7 +512,7 @@ Custom themes can be done in multiple ways. The easiest and fastest is to use th
}
```
You can alter the properties either for both scrollbars at once or per scrollbar axis:
You can alter the properties either for both scrollbars at once or per scrollbar axis. In the example below I've chosen `os-theme-custom` as the theme name:
```scss
// horizontal and vertical scrollbar are 10px
@@ -525,6 +530,16 @@ Custom themes can be done in multiple ways. The easiest and fastest is to use th
}
```
You can then use your theme by assigning it via the `scrollbars.theme` option:
```js
OverlayScrollbars(document.body, {
scrollbars: {
theme: 'os-theme-custom'
}
});
```
Since scrollbar styles are usually simple, this set of options should be enough to get your desired styling.
In case you need more freedom you can create your own styles by adding styling to the base class names described in the next section.
@@ -564,6 +579,13 @@ Custom themes can be done in multiple ways. The easiest and fastest is to use th
If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
### Gotchas
Its important that the chosen theme class name in your CSS file matches the assigned theme name in the options. If the CSS class name is `.my-theme` the `scrollbars.theme` has to be `'my-theme'`.
Please be aware of your stack. `css-modules` for example will alter your class names to prevent naming collisions. Always double check if your CSS is really what you expect it to be.
</details>
## Plugins