Note: For now please refer to the TypeScript definitions for a more detailed description of all possibilities.

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

// Both initializations have the same outcome

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

In the initialization object you can specify how the library is handling generated elements. For example you can appoint an existing element as the viewport element. Like this the library won't generate it but take the specified element instead:

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 generate its own elements. Those cases arise very often when you want an other library to work together with OverlayScrollbars.

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

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

And last but not least you can decide when the initialization should be canceled:

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

In the above example the initialization is canceled when the native scrollbars are overlaid or when your target is a body element and the plugin determined that a initialization to the body element would affect native functionality like window.scrollTo.

The default options are:

const defaultOptions = {
  paddingAbsolute: false,
  showNativeOverlaidScrollbars: false,
  update: {
    elementEvents: [['img', 'load']],
    debounce: [0, 33],
    attributes: null,
    ignoreMutation: null,
  },
  overflow: {
    x: 'scroll',
    y: 'scroll',
  },
  scrollbars: {
    theme: 'os-theme-dark',
    visibility: 'auto',
    autoHide: 'never',
    autoHideDelay: 1300,
    dragScroll: true,
    clickScroll: false,
    pointers: ['mouse', 'touch', 'pen'],
  },
};

paddingAbsolute

Indicates whether the padding for the content shall be absolute.

showNativeOverlaidScrollbars

Indicates whether the native overlaid scrollbars shall be visible.

update.elementEvents

An array of tuples. The first value in the tuple is an selector and the second value are event names. 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 img element emits an load event."

update.debounce

Note: If 0 is used for the timeout, requestAnimationFrame instead of setTimeout is used for the debounce.

Debounces the MutationObserver which tracks changes to the content. If a tuple is passed, the first value is the timeout and second is the max wait. If only a number is passed you specify only the timeout and there is no max wait. With null there is no debounce. Usefull to fine-tune performance.

update.attributes

Note: There is a base array of attributes that the MutationObserver always observes, even if this option is null.

An array of additional attributes that the MutationObserver should observe for the content.

update.ignoreMutation

A function which receives a MutationRecord as an argument. If the function returns a truthy value the mutation will be ignored and the plugin won't update. Usefull to fine-tune performance.

overflow.x

Note: Valid values are: 'hidden', 'scroll', 'visible', 'visible-hidden' and 'visible-scroll'.

The overflow behavior for the horizontal (x) axis.

overflow.y

Note: Valid values are: 'hidden', 'scroll', 'visible', 'visible-hidden' and 'visible-scroll'.

The overflow behavior for the vertical (y) axis.

scrollbars.theme

Applies the specified theme (classname) to the scrollbars.

scrollbars.visibility

Note: Valid values are: 'visible', 'hidden', and 'auto'.

The base visibility of the scrollbars.

scrollbars.autoHide

Note: Valid values are: 'never', 'scroll', 'leave' and 'move'.

The possibility to hide visible scrollbars automatically after a certain user action.

scrollbars.autoHideDelay

The delay in milliseconds before the scrollbars are hidden automatically.

scrollbars.dragScroll

Indicates whether you can drag the scrollbar handles for scrolling.

scrollbars.clickScroll

Note: This options requires the ClickScrollPlugin to work.

Indicates whether you can click on the scrollbar track for scrolling.

scrollbars.pointers

The PointerTypes the plugin should react to.

Note: Every event receives the instance from which it was invoked as the first argument. Always.

initialized

Is invoked after all generated elements, observers and events were appended to the DOM.

updated

Note: If an update was triggered but nothing changed, the event won't be invoked.

Is invoked after the instace was updated.

destroyed

Is invoked after all generated elements, observers and events were removed from the DOM.

scroll

Is invoked by scrolling the viewport.

CSS Custom properties

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

.os-scrollbar {
  // The size of the scrollbar
  --os-size: 0;
  // The axis-perpedicular 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-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
  --os-handle-perpendicular-size: 100%;
  // The :hover axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
  --os-handle-perpendicular-size-hover: 100%;
  // The :active axis-perpedicular 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 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:

// horizontal and vertical scrollbar are 10px 
.os-theme-custom {
  --os-size: 10px;
}

// horizontal scrollbar is 10px
.os-theme-custom.os-scrollbar-horizontal {
  --os-size: 10px;
}
// vertical scrollbar is 20px
.os-theme-custom.os-scrollbar-vertical {
  --os-size: 20px;
}

You can then use your theme by assigning it via the scrollbars.theme option:

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.

Scrollbars structure and CSS class names

The scrollbars HTML markup looks like:

<div class="os-scrollbar os-scrollbar-horizontal">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>
<div class="os-scrollbar os-scrollbar-vertical">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>

The class names are simplified, in a real application the .os-scrollbar element can have additional class names which modify the appearance (mostly visibility and alignment).

Below is a list of the most important class names you will encounter:

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.

If you applied OverlayScrollbars to the body element you can use window.scrollX, window.scrollY, window.scroll, window.scrollTo, window.scrollBy or any other native api.

If the plugin was applied to any other element you have to get the viewport element with the instance.elements() function first. With this element you can use element.scrollTop, element.scrollLeft, element.scroll, element.scrollTo, element.scrollBy or any other native api.

const { viewport } = osInstance.elements();
const { scrollLeft, scrollTop } = viewport; // get scroll offset
viewport.scrollTo({ top: 0 }); // set scroll offset

You can adjust a scrollbars handle length by setting a min-width / min-height and max-width / max-height style:

/* horizontal boundaries */
.os-scrollbar-horizontal .os-scrollbar-handle {
  min-width: 50px;
  max-width: 200px;
}
/* vertical boundaries */
.os-scrollbar-vertical .os-scrollbar-handle {
  min-height: 40px;
  max-height: 40px;
}

You can assign the same value to both properties to force the scrollbar to be always the same size.
Setting the width and height properties won't work since those are set by the plugin automatically.