Website   •   Examples

OverlayScrollbars

A javascript scrollbar plugin that hides the native scrollbars, provides custom styleable overlay scrollbars, and preserves the native functionality and feel.

Why?

I created this plugin because I hate ugly and space-consuming scrollbars. Similar plugins didn't meet my requirements in terms of features, quality, simplicity, license or browser support.

Goals & Features

• Simple, powerful and well-documented API.
• High browser compatibility - Firefox 59+, Chrome 55+, Opera 42+, Edge 15+ and Safari 10+.
• Fully Accessible - Native scrolling behavior is fully preserved.
• Can run on the server (Node, Deno and Bun) - 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 required.
• Leverage latest browser features - best performance in new browsers.
• Flow independent - supports all values for direction, flex-direction and writing-mode.
• Supports scroll snapping.
• Supports all virtual scrolling libraries.
• Supports the body element.
• Easy and effective scrollbar styling.
• Highly customizable.
• TypeScript support - completely written in TypeScript.
• Dependency-free - 100% self-written to ensure small size and best functionality.
• High quality and fully typed framework versions for react, vue, angular, svelte and solid.

Choose your framework

In addition to the vanilla JavaScript version, you can use the official framework components & utilities:

Getting started

npm & nodejs

OverlayScrollbars can be downloaded from npm or the package manager of your choice:

npm install overlayscrollbars

Once installed, it can be imported:

import 'overlayscrollbars/overlayscrollbars.css';
import { 
  OverlayScrollbars, 
  ScrollbarsHidingPlugin, 
  SizeObserverPlugin, 
  ClickScrollPlugin 
} from 'overlayscrollbars';

Note: If the path 'overlayscrollbars/overlayscrollbars.css' is not working use 'overlayscrollbars/styles/overlayscrollbars.css' as the import path for the CSS file.

You can use this Node Example as an reference / starting point.

Manual Download & Embedding

You can use OverlayScrollbars without any bundler or package manager.
Simply download one of the Releases or use a CDN.

• Use the javascript files with the .browser extension.
• Use the javascript files with the .es5 extension if you need to support older browsers, otherwise use the .es6 files.
• For production use the javascript / stylesheet files with the .min extension.

Embed OverlayScrollbars manually in your HTML:

<link type="text/css" href="https://github.com/KingSora/OverlayScrollbars/raw/v2.16.0/path/to/overlayscrollbars.css" rel="stylesheet" />
<script type="text/javascript" src="https://github.com/KingSora/OverlayScrollbars/raw/v2.16.0/path/to/overlayscrollbars.browser.es.js" defer></script>

Use the global variable OverlayScrollbarsGlobal to access the api similar to how you can do it in nodejs / modules:

var { 
  OverlayScrollbars, 
  ScrollbarsHidingPlugin, 
  SizeObserverPlugin, 
  ClickScrollPlugin  
} = OverlayScrollbarsGlobal;

You can use this Browser Example as an reference or a starting point.

The examples in this documentation use the import syntax instead of the OverlayScrollbarsGlobal object. However, both versions are equivalent.

Initialization

The initialization of OverlayScrollbars is explicit per element. Only the scrollbars of the element on which the plugin is initialized will be changed. Scrollbars of child elements will remain unchanged unless the plugin is initialized on them as well.

You can either initialize a new instance directly with an Element or with an Object where you have more control over the initialization process.

// Simple initialization with an element
const osInstance = OverlayScrollbars(document.querySelector('#myElement'), {});

Bridging initialization flickering

When you initialize OverlayScrollbars, it takes a few milliseconds to create and append all the elements to the DOM. During this time, the native scrollbars are still visible and will be switched out after the initialization is finished. This is seen as flickering.

To fix this behavior apply the data-overlayscrollbars-initialize attribute to the target element (and the html element as well when initializing a scrollbar for the body element).

<html data-overlayscrollbars-initialize>
  <head></head>
  <body data-overlayscrollbars-initialize></body>
</html>





  OverlayScrollbars is applied to this div

Note: When the browser is not executing JavaScript, bridging initialization flickering will cause the native scrollbars to no be visible at all. If you want to support such a case, you can use the overlayscrollbars.scriptingenabled.css file instead. Please be aware of the browser support of the scripting CSS media feature.

Initialization with an Object

This is an in depth topic. Click here to read it.

The only required field is the target field. This is the field to which the plugin will be applied.
If you use the object initialization with only the target field, the result is equivalent to the element initialization:

// Both initializations have the same outcome

OverlayScrollbars(document.querySelector('#myElement'), {});
OverlayScrollbars({ target: document.querySelector('#myElement') }, {});

When initializing with an object you can specify how the library handles generated elements. For example, you can specify an existing element as the `viewport' element. Then the library won't generate it, but use the specified element instead:

```js OverlayScrollbars({ target: document.querySelector('#target'), elements: { viewport: document.querySelector('#viewport'), }, }, {});

This is very useful if you have a fixed DOM structure and don't want OverlayScrollbars to create its own elements. These cases are very common when you want another library to work with OverlayScrollbars.

---

You can also decide to which element the scrollbars should be applied to:

 ```js
OverlayScrollbars({ 
  target: document.querySelector('#target'),
  scrollbars: {
    slot: document.querySelector('#target').parentElement,
  },
}, {});

Last but not least, you can decide when to cancel the initialization:

js OverlayScrollbars({ target: document.querySelector('#target'), cancel: { nativeScrollbarsOverlaid: true, body: null, } }, {});

In the above example, the initialization will be aborted if the native scrollbars are overlaid, or if your target is a body element and the plugin has determined that initializing to the body element would interfere with native functionality such as window.scrollTo.

Styling

OverlayScrollbars provides a set of CSS Custom Properties which makes styling easy and fast.

Out of the box you can choose between two scrollbar themes called os-theme-dark and os-theme-light. You can use the scrollbars.theme option to change the theme.

Custom scrollbar themes can be done in several ways. The easiest and fastest way is to use the predefined set of CSS Custom Properties aka CSS variables. If that's not enough, you can add custom class names or add custom styling to the existing class names.

Styling in depth

This is an in depth topic. Click here to read it.

### CSS Custom properties

OverlayScrollbars provides the following CSS Custom Properties:

Viewport styling:

scss [data-overlayscrollbars-viewport] { overflow-x: var(--os-viewport-overflow-x); overflow-y: var(--os-viewport-overflow-y); }

You can use the --os-viewport-overflow-x and --os-viewport-overflow-y properties to re-apply the correct overflow styles in case other styling rules (e.g. from 3rd party libraries) are overwriting them.

Scrollbar styling:

scss .os-scrollbar { // The size of the scrollbar --os-size: 0; // The axis-perpendicular padding of the scrollbar (horizontal: padding-y, vertical: padding-x) --os-padding-perpendicular: 0; // The axis padding of the scrollbar (horizontal: padding-x, vertical: padding-y) --os-padding-axis: 0; // The border radius of the scrollbar track --os-track-border-radius: 0; // The background of the scrollbar track --os-track-bg: none; // The :hover background of the scrollbar track --os-track-bg-hover: none; // The :active background of the scrollbar track --os-track-bg-active: none; // The border of the scrollbar track --os-track-border: none; // The :hover background of the scrollbar track --os-track-border-hover: none; // The :active background of the scrollbar track --os-track-border-active: none; // The border radius of the scrollbar handle --os-handle-border-radius: 0; // The background of the scrollbar handle --os-handle-bg: none; // The :hover background of the scrollbar handle --os-handle-bg-hover: none; // The :active background of the scrollbar handle --os-handle-bg-active: none; // The border of the scrollbar handle --os-handle-border: none; // The :hover border of the scrollbar handle --os-handle-border-hover: none; // The :active border of the scrollbar handle --os-handle-border-active: none; // The min size of the scrollbar handle --os-handle-min-size: 33px; // The max size of the scrollbar handle --os-handle-max-size: none; // The axis-perpendicular size of the scrollbar handle (horizontal: height, vertical: width) --os-handle-perpendicular-size: 100%; // The :hover axis-perpendicular size of the scrollbar handle (horizontal: height, vertical: width) --os-handle-perpendicular-size-hover: 100%; // The :active axis-perpendicular size of the scrollbar handle (horizontal: height, vertical: width) --os-handle-perpendicular-size-active: 100%; // Increases the interactive area of the scrollbar handle. --os-handle-interactive-area-offset: 0; }

You can change the properties for both scrollbars at once, or for each scrollbar axis. In the example below, I've chosen os-theme-custom as the