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:

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:

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

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

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.

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,
    autoHideSuspend: false,
    dragScroll: true,
    clickScroll: false,
    pointers: ['mouse', 'touch', 'pen'],
  },
};

paddingAbsolute

Indicates whether the padding for the content should be absolute.

showNativeOverlaidScrollbars

Indicates whether the native overlaid scrollbars should 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 emits any of the specified events. The default value can be interpreted as "The plugin will update itself if any img element emits a load event."

update.debounce

Note: If 0 is used for the timeout, requestAnimationFrame will be used instead of setTimeout 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 it is treated as the timeout and there is no max wait. With null there is no debounce. Useful 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 the content for.

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. Useful 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 visibility of a scrollbar if its scroll axis is able to have a scrollable overflow. (Scrollable overflow for an axis is only possible with the overflow behavior set to 'scroll' or 'visible-scroll').

scrollbars.autoHide

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

Dictates whether to hide visible scrollbars automatically after a certain user action.

scrollbars.autoHideDelay

The delay in milliseconds before the scrollbars are automatically hidden.

scrollbars.autoHideSuspend

Suspend the autoHide functionality until the first scroll interaction is performed.
The default value for this option is false for backwards compatibility reasons but is recommended to be true for better accessibility.

scrollbars.dragScroll

Indicates whether you can drag the scrollbar handles for scrolling.

scrollbars.clickScroll

Note: If set to true the ClickScrollPlugin is required.

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

scrollbars.pointers

The PointerTypes the plugin should react to.

TypeScript

// The options of a OverlayScrollbars instance.
type Options = {
  // Whether the padding should be absolute.
  paddingAbsolute: boolean;
  // Whether to show the native scrollbars. Has effect only if the native scrollbars are overlaid.
  showNativeOverlaidScrollbars: boolean;
  // Customizes the automatic update behavior.
  update: {
    /**
     * The given Event(s) from the elements with the given selector(s) will trigger an update.
     * Useful for everything the MutationObserver and ResizeObserver can't detect
     * e.g.: An image's `load` event or the `transitionend` / `animationend` events.
     */
    elementEvents: Array<[elementSelector: string, eventNames: string]> | null;
    /**
     * The debounce which is used to detect content changes.
     * If a tuple is provided you can customize the `timeout` and the `maxWait` in milliseconds.
     * If a single number customizes only the `timeout`.
     *