mirror of
https://github.com/tenrok/OverlayScrollbars.git
synced 2026-05-17 06:19:39 +03:00
Rene Haas
224 lines
58 KiB
HTML
224 lines
58 KiB
HTML
<!DOCTYPE html><html lang="en" data-overlayscrollbars-initialize=""><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><title>OverlayScrollbars</title><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><meta name="next-head-count" content="14"/><link rel="preload" href="/OverlayScrollbars/_next/static/css/5a6c15b2dc230309.css" as="style"/><link rel="stylesheet" href="/OverlayScrollbars/_next/static/css/5a6c15b2dc230309.css" data-n-g=""/><link rel="preload" href="/OverlayScrollbars/_next/static/css/054cd89f2e050c9e.css" as="style"/><link rel="stylesheet" href="/OverlayScrollbars/_next/static/css/054cd89f2e050c9e.css" data-n-p=""/><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-0d224bd9e3d9990c.js" defer=""></script><script src="/OverlayScrollbars/_next/static/chunks/pages/index-d0071a39b860db74.js" defer=""></script><script src="/OverlayScrollbars/_next/static/H7XSE--jMO2dm1KsKCI3u/_buildManifest.js" defer=""></script><script src="/OverlayScrollbars/_next/static/H7XSE--jMO2dm1KsKCI3u/_ssgManifest.js" defer=""></script></head><body data-overlayscrollbars-initialize=""><div id="__next"><div class="font-sans font-normal text-primary-dark"><div class="px-6 sm:container"><div class="mt-8 flex justify-center items-center h-[33vh] min-h-32 max-h-40 xxs:max-h-44"><div class="h-full assets_logo__UC59w"><img src="/OverlayScrollbars/_next/static/media/logo.5dcad24b.svg" class="h-full" alt="OverlayScrollbars Logo" width="200" height="200"/></div></div><h1 class="text-center xxs:text-4xl text-2xl font-bold my-11">Overlay<wbr/>Scrollbars</h1><p class="text-center mx-auto max-w-screen-sm my-11 font-medium">A javascript scrollbar plugin that hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling.</p><div class="my-6 text-center font-medium text-sm uppercase relative"><span class="p-3 bg-white">used by<div class="absolute block top-1/2 left-1/2 w-[100%] xs:w-[80%] border-t-[1px] border-slate-300 translate-x-[-50%] translate-y-[-50%] z-[-1]"></div></span></div><div data-overlayscrollbars-initialize=""><div><div class="flex justify-center"><div class="inline-flex items-center gap-6 py-6 assets_usedBy__FHTGG"><div class="h-11 px-3 flex-grow flex-shrink-0" style="filter:brightness(0.35)"><img class="h-full" src="/OverlayScrollbars/_next/static/media/spotify-logo.0dffbf88.svg" alt=""/></div><div class="h-11 px-3 py-1.5 flex-grow flex-shrink-0"><img class="h-full" src="/OverlayScrollbars/_next/static/media/storybook-logo.e62f5bdf.svg" alt=""/></div><div class="h-11 p-3 flex-grow flex-shrink-0"><img class="h-full" src="/OverlayScrollbars/_next/static/media/adminlte-logo.22257d89.png" alt=""/></div></div></div></div></div><div class="my-6 text-center font-medium text-sm uppercase relative"><span class="p-3 bg-white"><a href="https://github.com/KingSora/OverlayScrollbars" target="_blank" rel="noreferrer"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" class="default:fill-current inline-block w-11 hover:scale-110 text-primary-dark hover:text-primary-blue1 active:text-primary-blue2 transition-transformColor ease-in-out duration-300"><use href="/OverlayScrollbars/_next/static/media/github.f9873dbb.svg#github"></use></svg><span class="sr-only">OverlayScrollbars on Github</span></a><div class="absolute block top-1/2 left-1/2 w-[100%] xs:w-[80%] border-t-[1px] border-slate-300 translate-x-[-50%] translate-y-[-50%] z-[-1]"></div></span></div><p class="text-center text-sm text-primary-gray2 mx-auto max-w-screen-sm my-11 font-medium">This page is a work in progress. For now refer to the TypeScript definitions for a more detailed documentation.<br/>Looking for the v1 docs?<!-- --> <a href="v1" class="text-primary-blue2 underline">Follow this link</a>.</p><div class="mx-auto flex sm:flex-row justify-center gap-2 items-center flex-wrap"><a href="https://www.npmjs.com/package/overlayscrollbars"><img class="min-h-[20px]" src="https://img.shields.io/npm/dm/overlayscrollbars.svg?style=flat-square" alt="Downloads"/></a><a href="https://www.npmjs.com/package/overlayscrollbars"><img class="min-h-[20px]" src="https://img.shields.io/npm/v/overlayscrollbars.svg?style=flat-square" alt="Version"/></a><a href="https://github.com/KingSora/OverlayScrollbars/blob/master/LICENSE"><img class="min-h-[20px]" src="https://img.shields.io/github/license/kingsora/overlayscrollbars.svg?style=flat-square" alt="License"/></a><a href="https://app.codecov.io/gh/KingSora/OverlayScrollbars"><img class="min-h-[20px]" src="https://img.shields.io/codecov/c/github/KingSora/OverlayScrollbars?style=flat-square" alt="Code Coverage"/></a><a href="https://bundlephobia.com/package/overlayscrollbars"><img class="min-h-[20px]" src="https://img.shields.io/bundlephobia/minzip/overlayscrollbars?label=max.%20bundle%20size&style=flat-square" alt="Max. Bundle Size"/></a></div><div class="mt-11 prose prose-primary mx-auto pb-32"><h2>Why</h2>
|
|
<p>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.</p>
|
|
<h2>Goals & Features</h2>
|
|
<ul>
|
|
<li>Simple, powerful and good documented API</li>
|
|
<li>High browser compatibility - <b>Firefox</b>, <b>Chrome</b>, <b>Opera</b>, <b>Edge</b>, <b>Safari 10+</b> and <b>IE 11</b></li>
|
|
<li>Can be run on the server - <b>SSR</b>, <b>SSG</b> and <b>ISR</b> support</li>
|
|
<li>Tested on various devices - <b>Mobile</b>, <b>Desktop</b> and <b>Tablet</b></li>
|
|
<li>Tested with various (and mixed) inputs - <b>Mouse</b>, <b>touch</b> and <b>pen</b></li>
|
|
<li><b>Treeshaking</b> - bundle only what you really need</li>
|
|
<li>Automatic update detection - <b>no polling</b></li>
|
|
<li>Usage of latest browser features - best <b>performance</b> in new browsers</li>
|
|
<li>Bidirectional - LTR or RTL direction support</li>
|
|
<li>Simple and effective scrollbar styling</li>
|
|
<li>Highly customizable</li>
|
|
<li>TypeScript support - fully written in TypeScript</li>
|
|
<li>Dependency free - 100% self written to ensure small size and best functionality</li>
|
|
<li>High quality and fully typed Framework versions for <a href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react"><code>react</code></a>, <a href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue"><code>vue</code></a>, <a href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx"><code>angular</code></a>, <a href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-svelte"><code>svelte</code></a> and <a href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-solid"><code>solid</code></a>.</li>
|
|
</ul>
|
|
<h2>Choose your framework</h2>
|
|
<p>Additionally to the vanilla JavaScript version you can use the official framework components & utilities:</p>
|
|
<div class="flex flex-wrap"><a class="flex-grow-0 flex-shrink-0" href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react"><img class="h-[80px] mx-1 my-1" src="https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/packages/overlayscrollbars-react/logo.svg" width="80" height="80" alt="React"/></a><a class="flex-grow-0 flex-shrink-0" href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue"><img class="h-[80px] mx-1 my-1" src="https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/packages/overlayscrollbars-vue/logo.svg" width="80" height="80" alt="Vue"/></a><a class="flex-grow-0 flex-shrink-0" href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx"><img class="h-[80px] mx-1 my-1" src="https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/packages/overlayscrollbars-ngx/logo.svg" width="80" height="80" alt="Angular"/></a><a class="flex-grow-0 flex-shrink-0" href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-svelte"><img class="h-[80px] mx-1 my-1" src="https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/packages/overlayscrollbars-svelte/logo.svg" width="80" height="80" alt="Svelte"/></a><a class="flex-grow-0 flex-shrink-0" href="https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-solid"><img class="h-[80px] mx-1 my-1" src="https://raw.githubusercontent.com/KingSora/OverlayScrollbars/master/packages/overlayscrollbars-solid/logo.svg" width="80" height="80" alt="Solid"/></a></div>
|
|
<h2>Getting started</h2>
|
|
<h3>npm & node</h3>
|
|
<p>OverlayScrollbars can be downloaded from <a href="https://www.npmjs.com/package/overlayscrollbars">npm</a> or the package manager of your choice:</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="sh" data-theme="default"><span class="line"><span style="color:#657B83">npm install overlayscrollbars</span></span></code></div></pre></div>
|
|
<p>After installation it can be imported:</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#859900">import</span><span style="color:#657B83"> </span><span style="color:#2AA198">'overlayscrollbars/overlayscrollbars.css'</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#859900">import</span><span style="color:#657B83"> { </span><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83"> } </span><span style="color:#859900">from</span><span style="color:#657B83"> </span><span style="color:#2AA198">'overlayscrollbars'</span><span style="color:#657B83">;</span></span></code></div></pre></div>
|
|
<blockquote>
|
|
<p><strong>Note</strong>: In older node versions use <code>'overlayscrollbars/styles/overlayscrollbars.css'</code> as the import path for the CSS file.</p>
|
|
</blockquote>
|
|
<h3>Manual download & embedding</h3>
|
|
<details><summary><p>These instructions are for quick prototyping or old stacks. Click here to read them.</p></summary><br/><p>You can use OverlayScrollbars without any bundler or package manager.<br/>
|
|
<!-- -->Simply download it from the <a href="https://github.com/KingSora/OverlayScrollbars/releases">Releases</a> or use a <a href="https://cdnjs.com/libraries/overlayscrollbars">CDN</a>.</p><ul>
|
|
<li>Use the javascript files with the <code>.browser</code> extension.</li>
|
|
<li>If you target old browsers use the <code>.es5</code> javascript file, for new browsers <code>.es6</code>.</li>
|
|
<li>For production use the javascript / stylesheet files with the <code>.min</code> extension.</li>
|
|
</ul><p>Embedd OverlayScrollbars manually in your HTML:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="html" data-theme="default"><span class="line"><span style="color:#93A1A1"><</span><span style="color:#268BD2">link</span><span style="color:#657B83"> </span><span style="color:#93A1A1">type</span><span style="color:#657B83">=</span><span style="color:#2AA198">"text/css"</span><span style="color:#657B83"> </span><span style="color:#93A1A1">href</span><span style="color:#657B83">=</span><span style="color:#2AA198">"path/to/overlayscrollbars.css"</span><span style="color:#657B83"> </span><span style="color:#93A1A1">rel</span><span style="color:#657B83">=</span><span style="color:#2AA198">"stylesheet"</span><span style="color:#657B83"> </span><span style="color:#93A1A1">/></span></span>
|
|
<span class="line"><span style="color:#93A1A1"><</span><span style="color:#268BD2">script</span><span style="color:#657B83"> </span><span style="color:#93A1A1">type</span><span style="color:#657B83">=</span><span style="color:#2AA198">"text/javascript"</span><span style="color:#657B83"> </span><span style="color:#93A1A1">src</span><span style="color:#657B83">=</span><span style="color:#2AA198">"path/to/overlayscrollbars.js"</span><span style="color:#657B83"> </span><span style="color:#93A1A1">defer></</span><span style="color:#268BD2">script</span><span style="color:#93A1A1">></span></span></code></div></pre></div><p>You can use the global variable <code>OverlayScrollbarsGlobal</code> to access the api:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#586E75;font-style:italic">var</span><span style="color:#657B83"> </span><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83"> </span><span style="color:#859900">=</span><span style="color:#657B83"> </span><span style="color:#268BD2">OverlayScrollbarsGlobal</span><span style="color:#657B83">.</span><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">(</span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">body</span><span style="color:#657B83">, {});</span></span></code></div></pre></div></details>
|
|
<h2>Initialization</h2>
|
|
<blockquote>
|
|
<p><strong>Note</strong>: During initialization its expected that the <b>CSS file is loaded and parsed</b> by the browser.</p>
|
|
</blockquote>
|
|
<p>You can initialize either directly with an <code>Element</code> or with an <code>Object</code> where you have more control over the initialization process.</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#93A1A1">// simple initialization with an element</span></span>
|
|
<span class="line"><span style="color:#586E75;font-style:italic">const</span><span style="color:#657B83"> </span><span style="color:#268BD2">osInstance</span><span style="color:#657B83"> </span><span style="color:#859900">=</span><span style="color:#657B83"> </span><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">(</span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#myElement'</span><span style="color:#657B83">), {});</span></span></code></div></pre></div>
|
|
<h3>Bridging initialization flickering</h3>
|
|
<p>If you initialize OverlayScrollbars it needs a few milliseconds to create and append all the elements to the DOM.
|
|
While this period the native scrollbars are still visible and are switched out after the initialization is finished. This is perceived as flickering.</p>
|
|
<p>To fix this behavior apply the <code>data-overlayscrollbars-initialize</code> attribute to the target element (and <code>html</code> element if the target element is <code>body</code>).</p>
|
|
<h3>Initialization with an Object</h3>
|
|
<details><summary><p>This is a in depth topic. Click here to read it.</p></summary><br/><blockquote>
|
|
<p><strong>Note</strong>: For now please refer to the <b>TypeScript definitions</b> for a more detailed description of all possibilities.</p>
|
|
</blockquote><p>The only required field is the <code>target</code> field. This is the field to which the plugin is applied to.<br/>
|
|
<!-- -->If you use the object initialization only with the <code>target</code> field, the outcome is equivalent to the element initialization:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#93A1A1">// Both initializations have the same outcome</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">(</span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#myElement'</span><span style="color:#657B83">), {});</span></span>
|
|
<span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">({ target: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#myElement'</span><span style="color:#657B83">) }, {});</span></span></code></div></pre></div><p>In the initialization object you can specify how the library is handling generated elements.
|
|
For example you can appoint an existing element as the <code>viewport</code> element. Like this the library won't generate it but take the specified element instead:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">({ </span></span>
|
|
<span class="line"><span style="color:#657B83"> target: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#target'</span><span style="color:#657B83">),</span></span>
|
|
<span class="line"><span style="color:#657B83"> elements: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> viewport: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#viewport'</span><span style="color:#657B83">),</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83">}, {});</span></span></code></div></pre></div><p>This is very useful if you have a fixed DOM structure and don't want OverlayScrollbars to generate its own elements. Those cases arise very often when you want an other library to work together with OverlayScrollbars.</p><hr/><p>You can also decide to which element the scrollbars should be applied to:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">({ </span></span>
|
|
<span class="line"><span style="color:#657B83"> target: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#target'</span><span style="color:#657B83">),</span></span>
|
|
<span class="line"><span style="color:#657B83"> scrollbars: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> slot: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#target'</span><span style="color:#657B83">).</span><span style="color:#268BD2">parentElement</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83">}, {});</span></span></code></div></pre></div><hr/><p>And last but not least you can decide when the initialization should be canceled:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">({ </span></span>
|
|
<span class="line"><span style="color:#657B83"> target: </span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#target'</span><span style="color:#657B83">),</span></span>
|
|
<span class="line"><span style="color:#657B83"> cancel: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> nativeScrollbarsOverlaid: </span><span style="color:#B58900">true</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> body: </span><span style="color:#B58900">null</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> }</span></span>
|
|
<span class="line"><span style="color:#657B83">}, {});</span></span></code></div></pre></div><p>In the above example the initialization is canceled when the native scrollbars are overlaid or when your target is a <code>body</code> element and the plugin determined that a initialization to the <code>body</code> element would affect native functionality like <code>window.scrollTo</code>.</p></details>
|
|
<h2>Options</h2>
|
|
<p>You can initialize OverlayScrollbars with an initial set of options, which can be changed at any time with the <code>options</code> method:</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">(</span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#myElement'</span><span style="color:#657B83">), {</span></span>
|
|
<span class="line"><span style="color:#657B83"> overflow: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> x: </span><span style="color:#2AA198">'hidden'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83">});</span></span></code></div></pre></div>
|
|
<h3>Options in depth</h3>
|
|
<details><summary><p>This is a in depth topic. Click here to read it.</p></summary><br/><p>The default options are:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#586E75;font-style:italic">const</span><span style="color:#657B83"> </span><span style="color:#268BD2">defaultOptions</span><span style="color:#657B83"> </span><span style="color:#859900">=</span><span style="color:#657B83"> {</span></span>
|
|
<span class="line"><span style="color:#657B83"> paddingAbsolute: </span><span style="color:#B58900">false</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> showNativeOverlaidScrollbars: </span><span style="color:#B58900">false</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> update: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> elementEvents: [[</span><span style="color:#2AA198">'img'</span><span style="color:#657B83">, </span><span style="color:#2AA198">'load'</span><span style="color:#657B83">]],</span></span>
|
|
<span class="line"><span style="color:#657B83"> debounce: [</span><span style="color:#D33682">0</span><span style="color:#657B83">, </span><span style="color:#D33682">33</span><span style="color:#657B83">],</span></span>
|
|
<span class="line"><span style="color:#657B83"> attributes: </span><span style="color:#B58900">null</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> ignoreMutation: </span><span style="color:#B58900">null</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83"> overflow: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> x: </span><span style="color:#2AA198">'scroll'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> y: </span><span style="color:#2AA198">'scroll'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83"> scrollbars: {</span></span>
|
|
<span class="line"><span style="color:#657B83"> theme: </span><span style="color:#2AA198">'os-theme-dark'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> visibility: </span><span style="color:#2AA198">'auto'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> autoHide: </span><span style="color:#2AA198">'never'</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> autoHideDelay: </span><span style="color:#D33682">1300</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> dragScroll: </span><span style="color:#B58900">true</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> clickScroll: </span><span style="color:#B58900">false</span><span style="color:#657B83">,</span></span>
|
|
<span class="line"><span style="color:#657B83"> pointers: [</span><span style="color:#2AA198">'mouse'</span><span style="color:#657B83">, </span><span style="color:#2AA198">'touch'</span><span style="color:#657B83">, </span><span style="color:#2AA198">'pen'</span><span style="color:#657B83">],</span></span>
|
|
<span class="line"><span style="color:#657B83"> },</span></span>
|
|
<span class="line"><span style="color:#657B83">};</span></span></code></div></pre></div><h3><code>paddingAbsolute</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>boolean</code></td><td align="left"><code>false</code></td></tr></tbody></table><p>Indicates whether the padding for the content shall be absolute.</p><h3><code>showNativeOverlaidScrollbars</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>boolean</code></td><td align="left"><code>false</code></td></tr></tbody></table><p>Indicates whether the native overlaid scrollbars shall be visible.</p><h3><code>update.elementEvents</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>Array<[string, string]> | null</code></td><td align="left"><code>[['img', 'load']]</code></td></tr></tbody></table><p>An array of tuples. The first value in the tuple is an <code>selector</code> and the second value are <code>event names</code>. The plugin will update itself if any of the elements with the specified selector will emit any specified event. The default value can be interpreted as "The plugin will update itself if any <code>img</code> element emits an <code>load</code> event."</p><h3><code>update.debounce</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>[number, number] | number | null</code></td><td align="left"><code>[0, 33]</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: If 0 is used for the timeout, <code>requestAnimationFrame</code> instead of <code>setTimeout</code> is used for the debounce.</p>
|
|
</blockquote><p>Debounces the <code>MutationObserver</code> which tracks changes to the content. If a <strong>tuple</strong> is passed, the first value is the timeout and second is the max wait. If only a <strong>number</strong> is passed you specify only the timeout and there is no max wait. With <strong>null</strong> there is no debounce. <strong>Usefull to fine-tune performance.</strong></p><h3><code>update.attributes</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string[] | null</code></td><td align="left"><code>null</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: There is a base array of attributes that the <code>MutationObserver</code> always observes, even if this option is <code>null</code>.</p>
|
|
</blockquote><p>An array of additional attributes that the <code>MutationObserver</code> should observe for the content.</p><h3><code>update.ignoreMutation</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>((mutation) => any) | null</code></td><td align="left"><code>null</code></td></tr></tbody></table><p>A function which receives a <a href="https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord"><code>MutationRecord</code></a> as an argument. If the function returns a truthy value the mutation will be ignored and the plugin won't update. <strong>Usefull to fine-tune performance.</strong></p><h3><code>overflow.x</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string</code></td><td align="left"><code>'scroll'</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: Valid values are: <code>'hidden'</code>, <code>'scroll'</code>, <code>'visible'</code>, <code>'visible-hidden'</code> and <code>'visible-scroll'</code>.</p>
|
|
</blockquote><p>The overflow behavior for the horizontal (x) axis.</p><h3><code>overflow.y</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string</code></td><td align="left"><code>'scroll'</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: Valid values are: <code>'hidden'</code>, <code>'scroll'</code>, <code>'visible'</code>, <code>'visible-hidden'</code> and <code>'visible-scroll'</code>.</p>
|
|
</blockquote><p>The overflow behavior for the vertical (y) axis.</p><h3><code>scrollbars.theme</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string | null</code></td><td align="left"><code>'os-theme-dark'</code></td></tr></tbody></table><p>Applies the specified theme (classname) to the scrollbars.</p><h3><code>scrollbars.visibility</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string</code></td><td align="left"><code>'auto'</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: Valid values are: <code>'visible'</code>, <code>'hidden'</code>, and <code>'auto'</code>.</p>
|
|
</blockquote><p>The base visibility of the scrollbars.</p><h3><code>scrollbars.autoHide</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string</code></td><td align="left"><code>'never'</code></td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: Valid values are: <code>'never'</code>, <code>'scroll'</code>, <code>'leave'</code> and <code>'move'</code>.</p>
|
|
</blockquote><p>The possibility to hide visible scrollbars automatically after a certain user action.</p><h3><code>scrollbars.autoHideDelay</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>number</code></td><td align="left"><code>1300</code></td></tr></tbody></table><p>The delay in milliseconds before the scrollbars are hidden automatically.</p><h3><code>scrollbars.dragScroll</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>boolean</code></td><td align="left"><code>true</code></td></tr></tbody></table><p>Indicates whether you can drag the scrollbar handles for scrolling.</p><h3><code>scrollbars.clickScroll</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>boolean</code></td><td align="left"><code>false</code></td></tr></tbody></table><p>Indicates whether you can click on the scrollbar track for scrolling.</p><h3><code>scrollbars.pointers</code></h3><table><thead><tr><th align="left">type</th><th align="left">default</th></tr></thead><tbody><tr><td align="left"><code>string[] | null</code></td><td align="left"><code>['mouse', 'touch', 'pen']</code></td></tr></tbody></table><p>The <a href="https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pointerType"><code>PointerTypes</code></a> the plugin should react to.</p></details>
|
|
<h2>Events</h2>
|
|
<p>You can initialize OverlayScrollbars with an initial set of events, which can be managed at any time with the <code>on</code> and <code>off</code> methods:</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">(</span><span style="color:#268BD2">document</span><span style="color:#657B83">.</span><span style="color:#268BD2">querySelector</span><span style="color:#657B83">(</span><span style="color:#2AA198">'#myElement'</span><span style="color:#657B83">), {}, {</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">updated</span><span style="color:#657B83">(osInstance, onUpdatedArgs) {</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#93A1A1">// ...</span></span>
|
|
<span class="line"><span style="color:#657B83"> }</span></span>
|
|
<span class="line"><span style="color:#657B83">});</span></span></code></div></pre></div>
|
|
<h3>Events in depth</h3>
|
|
<details><summary><p>This is a in depth topic. Click here to read it.</p></summary><br/><blockquote>
|
|
<p><strong>Note</strong>: Every event receives the <code>instance</code> from which it was invoked as the first argument. Always.</p>
|
|
</blockquote><h3><code>initialized</code></h3><table><thead><tr><th align="left">arguments</th><th align="left">description</th></tr></thead><tbody><tr><td align="left"><code>instance</code></td><td align="left">The instance which invoked the event.</td></tr></tbody></table><p>Is invoked after all generated elements, observers and events were appended to the DOM.</p><h3><code>updated</code></h3><table><thead><tr><th align="left">arguments</th><th align="left">description</th></tr></thead><tbody><tr><td align="left"><code>instance</code></td><td align="left">The instance which invoked the event.</td></tr><tr><td align="left"><code>onUpdatedArgs</code></td><td align="left">An <code>object</code> which describes the update in detail.</td></tr></tbody></table><blockquote>
|
|
<p><strong>Note</strong>: If an update was triggered but nothing changed, the event won't be invoked.</p>
|
|
</blockquote><p>Is invoked after the instace was updated.</p><h3><code>destroyed</code></h3><table><thead><tr><th align="left">arguments</th><th align="left">description</th></tr></thead><tbody><tr><td align="left"><code>instance</code></td><td align="left">The instance which invoked the event.</td></tr><tr><td align="left"><code>canceled</code></td><td align="left">An <code>boolean</code> which indicates whether the initialization was canceled and thus destroyed.</td></tr></tbody></table><p>Is invoked after all generated elements, observers and events were removed from the DOM.</p><h3><code>scroll</code></h3><table><thead><tr><th align="left">arguments</th><th align="left">description</th></tr></thead><tbody><tr><td align="left"><code>instance</code></td><td align="left">The instance which invoked the event.</td></tr><tr><td align="left"><code>event</code></td><td align="left">The original <code>event</code> argument of the DOM event.</td></tr></tbody></table><p>Is invoked by scrolling the viewport.</p></details>
|
|
<h2>Instance</h2>
|
|
<blockquote>
|
|
<p><strong>Note</strong>: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.</p>
|
|
</blockquote>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="ts" data-theme="default"><span class="line"><span style="color:#586E75;font-style:italic">interface</span><span style="color:#657B83"> </span><span style="color:#CB4B16">OverlayScrollbars</span><span style="color:#657B83"> {</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">options</span><span style="color:#657B83">()</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Options</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">options</span><span style="color:#657B83">(newOptions</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">PartialOptions</span><span style="color:#657B83">, pure</span><span style="color:#859900">?:</span><span style="color:#657B83"> </span><span style="color:#859900">boolean</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Options</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">on</span><span style="color:#657B83">(eventListeners</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListeners</span><span style="color:#657B83">, pure</span><span style="color:#859900">?:</span><span style="color:#657B83"> </span><span style="color:#859900">boolean</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> () </span><span style="color:#586E75;font-style:italic">=></span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">on</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83"> </span><span style="color:#586E75;font-style:italic">extends</span><span style="color:#657B83"> </span><span style="color:#859900">keyof</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListenerArgs</span><span style="color:#657B83">>(name</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">N</span><span style="color:#657B83">, listener</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListener</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83">>)</span><span style="color:#859900">:</span><span style="color:#657B83"> () </span><span style="color:#586E75;font-style:italic">=></span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">on</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83"> </span><span style="color:#586E75;font-style:italic">extends</span><span style="color:#657B83"> </span><span style="color:#859900">keyof</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListenerArgs</span><span style="color:#657B83">>(name</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">N</span><span style="color:#657B83">, listener</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListener</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83">>[])</span><span style="color:#859900">:</span><span style="color:#657B83"> () </span><span style="color:#586E75;font-style:italic">=></span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">off</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83"> </span><span style="color:#586E75;font-style:italic">extends</span><span style="color:#657B83"> </span><span style="color:#859900">keyof</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListenerArgs</span><span style="color:#657B83">>(name</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">N</span><span style="color:#657B83">, listener</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListener</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83">>)</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">off</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83"> </span><span style="color:#586E75;font-style:italic">extends</span><span style="color:#657B83"> </span><span style="color:#859900">keyof</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListenerArgs</span><span style="color:#657B83">>(name</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">N</span><span style="color:#657B83">, listener</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListener</span><span style="color:#657B83"><</span><span style="color:#CB4B16">N</span><span style="color:#657B83">>[])</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">update</span><span style="color:#657B83">(force</span><span style="color:#859900">?:</span><span style="color:#657B83"> </span><span style="color:#859900">boolean</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">boolean</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">state</span><span style="color:#657B83">()</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">State</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">elements</span><span style="color:#657B83">()</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Elements</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">destroy</span><span style="color:#657B83">()</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83">}</span></span></code></div></pre></div>
|
|
<h2>Static Methods</h2>
|
|
<blockquote>
|
|
<p><strong>Note</strong>: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.</p>
|
|
</blockquote>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="ts" data-theme="default"><span class="line"><span style="color:#586E75;font-style:italic">interface</span><span style="color:#657B83"> </span><span style="color:#CB4B16">OverlayScrollbarsStatic</span><span style="color:#657B83"> {</span></span>
|
|
<span class="line"><span style="color:#657B83"> (target</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">InitializationTarget</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">OverlayScrollbars</span><span style="color:#657B83"> </span><span style="color:#859900">|</span><span style="color:#657B83"> </span><span style="color:#859900">undefined</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> (target</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">InitializationTarget</span><span style="color:#657B83">, options</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">PartialOptions</span><span style="color:#657B83">, eventListeners</span><span style="color:#859900">?:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">EventListeners</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">OverlayScrollbars</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">plugin</span><span style="color:#657B83">(plugin</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Plugin</span><span style="color:#657B83"> </span><span style="color:#859900">|</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Plugin</span><span style="color:#657B83">[])</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">void</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">valid</span><span style="color:#657B83">(osInstance</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#859900">any</span><span style="color:#657B83">)</span><span style="color:#859900">:</span><span style="color:#657B83"> osInstance </span><span style="color:#859900">is</span><span style="color:#657B83"> </span><span style="color:#CB4B16">OverlayScrollbars</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">env</span><span style="color:#657B83">()</span><span style="color:#859900">:</span><span style="color:#657B83"> </span><span style="color:#CB4B16">Environment</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83">}</span></span></code></div></pre></div>
|
|
<h2>Plugins</h2>
|
|
<p>Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins:</p>
|
|
<ul>
|
|
<li><strong>ScrollbarsHidingPlugin</strong>: Is needed for old browsers which aren't supporting nativ scrollbar styling features. <a href="https://caniuse.com/?search=scrollbar%20styling">You can find the list of browsers where you need this plugin here</a> (note that even though <code>iOS Safari >= 14</code> is marked as unsupported you only need this plugin for <code>iOS < 7.1</code>).</li>
|
|
<li><strong>SizeObserverPlugin</strong>: Is needed for old browsers which aren't supporting the <code>ResizeObserver</code> api. <a href="https://caniuse.com/?search=ResizeObserver">You can find the list of browsers where you need this plugin here</a></li>
|
|
<li><strong>ClickScrollPlugin</strong>: If you want to use the option <code>scrollbars: { clickScroll: true }</code>.</li>
|
|
</ul>
|
|
<h3>Consuming Plugins</h3>
|
|
<p>Plugins are consumed like:</p>
|
|
<div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="ts" data-theme="default"><span class="line"><span style="color:#859900">import</span><span style="color:#657B83"> { </span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">, </span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">ScrollbarsHidingPlugin</span><span style="color:#657B83">, </span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">SizeObserverPlugin</span><span style="color:#657B83">, </span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#268BD2">ClickScrollPlugin</span><span style="color:#657B83"> </span></span>
|
|
<span class="line"><span style="color:#657B83">} </span><span style="color:#859900">from</span><span style="color:#657B83"> </span><span style="color:#2AA198">'overlayscrollbars'</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#93A1A1">// single plugin</span></span>
|
|
<span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">.</span><span style="color:#268BD2">plugin</span><span style="color:#657B83">(</span><span style="color:#268BD2">ScrollbarsHidingPlugin</span><span style="color:#657B83">);</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#93A1A1">// multiple plugins</span></span>
|
|
<span class="line"><span style="color:#268BD2">OverlayScrollbars</span><span style="color:#657B83">.</span><span style="color:#268BD2">plugin</span><span style="color:#657B83">([</span><span style="color:#268BD2">SizeObserverPlugin</span><span style="color:#657B83">, </span><span style="color:#268BD2">ClickScrollPlugin</span><span style="color:#657B83">]);</span></span></code></div></pre></div>
|
|
<h3>Writing Plugins</h3>
|
|
<blockquote>
|
|
<p><strong>Note</strong>: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.</p>
|
|
</blockquote>
|
|
<p>You can write and publish your own Plugins. This section is a work in progress.</p>
|
|
<h2>FAQ</h2>
|
|
<details><summary><p>How do I <code>get / set</code> the <code>scroll position</code> of an element I applied the OverlayScrollbars to?</p></summary><br/><p>If you applied <code>OverlayScrollbars</code> to the <code>body</code> element you can use <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollX"><code>window.scrollX</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollY"><code>window.scrollY</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/scroll"><code>window.scroll</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo"><code>window.scrollTo</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollBy"><code>window.scrollBy</code></a> or any other native api.</p><p>If the plugin was applied to any other element you have to get the <code>viewport</code> element with the <code>instance.elements()</code> function first. With this element you can use <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop"><code>element.scrollTop</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollLeft"><code>element.scrollLeft</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scroll"><code>element.scroll</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo"><code>element.scrollTo</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollBy"><code>element.scrollBy</code></a> or any other native api.</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="js" data-theme="default"><span class="line"><span style="color:#586E75;font-style:italic">const</span><span style="color:#657B83"> { </span><span style="color:#268BD2">viewport</span><span style="color:#657B83"> } </span><span style="color:#859900">=</span><span style="color:#657B83"> </span><span style="color:#268BD2">osInstance</span><span style="color:#657B83">.</span><span style="color:#268BD2">elements</span><span style="color:#657B83">();</span></span>
|
|
<span class="line"><span style="color:#586E75;font-style:italic">const</span><span style="color:#657B83"> { </span><span style="color:#268BD2">scrollLeft</span><span style="color:#657B83">, </span><span style="color:#268BD2">scrollTop</span><span style="color:#657B83"> } </span><span style="color:#859900">=</span><span style="color:#657B83"> </span><span style="color:#268BD2">viewport</span><span style="color:#657B83">; </span><span style="color:#93A1A1">// get scroll offset</span></span>
|
|
<span class="line"><span style="color:#268BD2">viewport</span><span style="color:#657B83">.</span><span style="color:#268BD2">scrollTo</span><span style="color:#657B83">({ top: </span><span style="color:#D33682">0</span><span style="color:#657B83"> }); </span><span style="color:#93A1A1">// set scroll offset</span></span></code></div></pre></div></details>
|
|
<details><summary><p>Is it possible to <code>limit / adjust the scrollbar handle length</code>?</p></summary><br/><p>You can adjust a scrollbars handle length by setting a <code>min-width / min-height</code> and <code>max-width / max-height</code> style:</p><div data-rehype-pretty-code-fragment=""><pre data-overlayscrollbars-initialize=""><div><code data-language="css" data-theme="default"><span class="line"><span style="color:#93A1A1">/* horizontal boundaries */</span></span>
|
|
<span class="line"><span style="color:#93A1A1">.os-scrollbar-horizontal</span><span style="color:#657B83"> </span><span style="color:#93A1A1">.os-scrollbar-handle</span><span style="color:#657B83"> {</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#859900">min-width</span><span style="color:#657B83">: </span><span style="color:#D33682">50</span><span style="color:#859900">px</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#859900">max-width</span><span style="color:#657B83">: </span><span style="color:#D33682">200</span><span style="color:#859900">px</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83">}</span></span>
|
|
<span class="line"><span style="color:#93A1A1">/* vertical boundaries */</span></span>
|
|
<span class="line"><span style="color:#93A1A1">.os-scrollbar-vertical</span><span style="color:#657B83"> </span><span style="color:#93A1A1">.os-scrollbar-handle</span><span style="color:#657B83"> {</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#859900">min-height</span><span style="color:#657B83">: </span><span style="color:#D33682">40</span><span style="color:#859900">px</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83"> </span><span style="color:#859900">max-height</span><span style="color:#657B83">: </span><span style="color:#D33682">40</span><span style="color:#859900">px</span><span style="color:#657B83">;</span></span>
|
|
<span class="line"><span style="color:#657B83">}</span></span></code></div></pre></div><p>You can assign the same value to both properties to force the scrollbar to be always the same size.<br/>
|
|
<!-- -->Setting the <code>width</code> and <code>height</code> properties won't work since those are set by the plugin automatically.</p></details>
|
|
<h2>Feature comparison to <code>v1</code></h2>
|
|
<ul>
|
|
<li>The <code>scroll</code> function is missing. Planned as a <code>plugin</code>. (WIP)</li>
|
|
<li>Initialization to the <code>textarea</code> element isn't supported yet. Planned as a <code>plugin</code>. (WIP)</li>
|
|
</ul>
|
|
<h2>Future Plans</h2>
|
|
<ul>
|
|
<li>Provide plugin based support for missing features. (treeshakeable)</li>
|
|
<li>Frequent updates in terms of bug-fixes and enhancements. (always use latest browser features)</li>
|
|
<li>Improve tests. (unit & browser tests)</li>
|
|
</ul>
|
|
<h2>License</h2>
|
|
<p>MIT</p></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{}},"page":"/","query":{},"buildId":"H7XSE--jMO2dm1KsKCI3u","assetPrefix":"/OverlayScrollbars","nextExport":true,"autoExport":true,"isFallback":false,"scriptLoader":[]}</script></body></html> |