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/blob/master/path/to/overlayscrollbars.css" rel="stylesheet" />
<script type="text/javascript" src="https://github.com/KingSora/OverlayScrollbars/raw/master/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).

<!-- for the body element -->
<html data-overlayscrollbars-initialize>
  <head></head>
  <body data-overlayscrollbars-initialize></body>
</html>

<!-- for all other elements -->
<div data-overlayscrollbars-initialize>
  OverlayScrollbars is applied to this div
</div>

Initialization with an Object

Options

You can initialize OverlayScrollbars with an initial set of options, which can be changed at any time with the options method:

OverlayScrollbars(document.querySelector('#myElement'), {
  overflow: {
    x: 'hidden',
  },
});

Options in depth

Events

You can initialize OverlayScrollbars with an initial set of events, which can be managed at any time with the on and off methods:

OverlayScrollbars(document.querySelector('#myElement'), {}, {
  updated(osInstance, onUpdatedArgs) {
    // ...
  }
});

Events in depth

Instance

The OverlayScrollbars instance can be created by calling the OverlayScrollbars function with an element and options object.

const osInstance = OverlayScrollbars(document.body, {});

Instance Methods

Static Object

The static OverlayScrollbars object.

OverlayScrollbars.plugin(SomePlugin);

Static Object Methods

Styling

OverlayScrollbars comes with two themes called os-theme-dark and os-theme-light. You can use the scrollbars.theme option to change the theme.

Custom 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

Plugins

Anything that is not considered core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are omitted during treeshaking and won't end up in your final bundle. OverlayScrollbars ships with the following plugins:

• ScrollbarsHidingPlugin: Needed for old browsers that don't support native scrollbar styling. You can find the list of browsers where you need this plugin here (note that even though iOS Safari >= 14 is marked as unsupported, you only need this plugin for iOS < 7.1).
• SizeObserverPlugin: Needed for old browsers that don't support the ResizeObserver api. You can find the list of browsers that need this plugin here
• ClickScrollPlugin: If you want to use the option scrollbars: { clickScroll: true }.

Consuming Plugins

Plugins are consumed like:

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

// Single plugin
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);

// Multiple plugins
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);

Plugins in depth

FAQ

Feature comparison to v1

• The scroll function is missing. Planned as a plugin. (WIP)
• Initialization to the textarea element isn't supported yet. Planned as a plugin. (WIP)

Future Plans

• Provide plugin based support for missing features. (treeshakeable)
• Frequent updates in terms of bug-fixes and enhancements. (always use latest browser features)
• Improve tests. (unit & browser tests)

Used by

• Spotify
• IntelliJ IDEA
• Storybook
• Admin LTE
• and many more...

Sponsors

Thanks to BrowserStack for sponsoring open source projects and letting me test OverlayScrollbars for free.

License

MIT