OverlayScrollbars

// Both initializations have the same outcome
 
OverlayScrollbars(document.querySelector('#myElement'), {});
OverlayScrollbars({ target: document.querySelector('#myElement') }, {});

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

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

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

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'],
  },
};

// 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`.
     *
     * If the `timeout` is `0`, a debounce still exists (and is done via `requestAnimationFrame` instead of `setTimeout`).
     */
    debounce: [timeout: number, maxWait: number] | number | null;
    /**
     * HTML attributes which will trigger an update if they're changed.
     * Basic attributes like `id`, `class`, `style` etc. are always observed and don't have to be added explicitly.
     */
    attributes: string[] | null;
    // A function which makes it possible to ignore a content mutation or null if nothing should be ignored.
    ignoreMutation: ((mutation: MutationRecord) => any) | null;
  };
  // Customizes the overflow behavior per axis.
  overflow: {
    // The overflow behavior of the horizontal (x) axis.
    x: OverflowBehavior;
    // The overflow behavior of the vertical (y) axis.
    y: OverflowBehavior;
  };
  // Customizes appearance of the scrollbars.
  scrollbars: {
    // The scrollbar's theme. The theme value will be added as `class` to all `scrollbar` elements of the instance.
    theme: string | null;
    // The scrollbar's visibility behavior.
    visibility: ScrollbarsVisibilityBehavior;
    // The scrollbar's auto hide behavior.
    autoHide: ScrollbarsAutoHideBehavior;
    // The scrollbar's auto hide delay in milliseconds.
    autoHideDelay: number;
    // Whether the scrollbar's auto hide behavior is suspended until a scroll happened.
    autoHideSuspend: boolean;
    // Whether it is possible to drag the handle of a scrollbar to scroll the viewport.
    dragScroll: boolean;
    // Whether it is possible to click the track of a scrollbar to scroll the viewport.
    clickScroll: ScrollbarsClickScrollBehavior;
    // An array of pointer types that shall be supported.
    pointers: string[] | null;
  };
};
 
// The overflow behavior of an axis.
type OverflowBehavior =
  // No scrolling is possible and the content is clipped.
  | 'hidden'
  // No scrolling is possible and the content isn't clipped.
  | 'visible'
  // Scrolling is possible if there is an overflow.
  | 'scroll'
  /**
   * If the other axis has no overflow the behavior is similar to `visible`.
   * If the other axis has overflow the behavior is similar to `hidden`.
   */
  | 'visible-hidden'
  /**
   * If the other axis has no overflow the behavior is similar to `visible`.
   * If the other axis has overflow the behavior is similar to `scroll`.
   */
  | 'visible-scroll';
 
// The scrollbars visibility behavior.
type ScrollbarsVisibilityBehavior =
  // The scrollbars are always visible.
  | 'visible'
  // The scrollbars are always hidden.
  | 'hidden'
  // The scrollbars are only visibile if there is overflow.
  | 'auto';
 
// The scrollbars auto hide behavior
type ScrollbarsAutoHideBehavior =
  // The scrollbars are never hidden automatically.
  | 'never'
  // The scrollbars are hidden unless the user scrolls.
  | 'scroll'
  // The scrollbars are hidden unless the pointer moves in the host element or the user scrolls.
  | 'move'
  // The scrollbars are hidden if the pointer leaves the host element or unless the user scrolls.
  | 'leave';
 
// The scrollbar click scroll behavior.
type ScrollbarsClickScrollBehavior = boolean | 'instant';

// A mapping between event names and their listener arguments.
type EventListenerArgs = {
  // Dispatched after all elements are initialized and appended.
  initialized: [instance: OverlayScrollbars];
  // Dispatched after an update.
  updated: [instance: OverlayScrollbars, onUpdatedArgs: OnUpdatedEventListenerArgs];
  // Dispatched after all elements, observers and events are destroyed.
  destroyed: [instance: OverlayScrollbars, canceled: boolean];
  // Dispatched on scroll.
  scroll: [instance: OverlayScrollbars, event: Event];
};
 
interface OnUpdatedEventListenerArgs {
  // Hints which describe what changed in the DOM.
  updateHints: {
    // Whether the size of the host element changed.
    sizeChanged: boolean;
    // Whether the direction of the host element changed.
    directionChanged: boolean;
    // Whether the intrinsic height behavior changed.
    heightIntrinsicChanged: boolean;
    // Whether the overflow edge (clientWidth / clientHeight) of the viewport element changed.
    overflowEdgeChanged: boolean;
    // Whether the overflow amount changed.
    overflowAmountChanged: boolean;
    // Whether the overflow style changed.
    overflowStyleChanged: boolean;
    // Whether the scroll coordinates changed.
    scrollCoordinatesChanged: boolean;
    // Whether an host mutation took place.
    hostMutation: boolean;
    // Whether an content mutation took place.
    contentMutation: boolean;
  };
  // The changed options.
  changedOptions: PartialOptions;
  // Whether the update happened with force-invalidated cache.
  force: boolean;
}

// A simplified version of the OverlayScrollbars TypeScript interface.
interface OverlayScrollbars {
  // Get the current options of the instance.
  options(): Options;
  // Sets the current options of the instance.
  options(newOptions: PartialOptions, pure?: boolean): Options;
 
  // Adds event listeners to the instance.
  on(eventListeners: EventListeners, pure?: boolean): () => void;
  // Adds a single event listener to the instance.
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): () => void;
  // Adds multiple event listeners to the instance.
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): () => void;
 
  // Removes a single event listener from the instance.
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): void;
  // Removes multiple event listeners from the instance.
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): void;
 
  // Updates the instance.
  update(force?: boolean): boolean;
 
  // Gets the instance's state.
  state(): State;
 
  // Gets the instance's elements.
  elements(): Elements;
 
  // Destroys the instance and removes all added elements.
  destroy(): void;
 
  // Gets the instance modules instance of the passed plugin.
  plugin<P extends InstancePlugin>(osPlugin: P): InferInstancePluginModuleInstance<P> | undefined;
}
 
// Describes a OverlayScrollbars instances state.
interface State {
  // Describes the current padding in pixels.
  padding: TRBL;
  // Whether the current padding is absolute.
  paddingAbsolute: boolean;
  // The client width (x) & height (y) of the viewport in pixels.
  overflowEdge: XY<number>;
  // The overflow amount in pixels.
  overflowAmount: XY<number>;
  // The css overflow style of the viewport.
  overflowStyle: XY<OverflowStyle>;
  // Whether the viewport has an overflow.
  hasOverflow: XY<boolean>;
  // The scroll coordinates of the viewport.
  scrollCoordinates: {
    // The start (origin) scroll coordinates for each axis.
    start: XY<number>;
    // The end scroll coordinates for each axis.
    end: XY<number>;
  };
  // Whether the direction is considered rtl.
  directionRTL: boolean;
  // Whether the instance is considered destroyed.
  destroyed: boolean;
}
 
// Describes the elements of a OverlayScrollbars instance.
interface Elements {
  // The element the instance was applied to.
  target: HTMLElement;
  // The host element. It's the root of all other elements.
  host: HTMLElement;
  /**
   * The element responsible for the correct padding.
   * Depending on initialization it can be the same as the viewport element.
   */
  padding: HTMLElement;
  // The element responsible of the scrolling.
  viewport: HTMLElement;
  /**
   * The element responsible for holding the actual content.
   * Depending on initialization it can be the same as the viewport element.
   */
  content: HTMLElement;
  /**
   * The element through which you can get the current `scrollLeft` or `scrollTop` offset.
   * Depending on the target element it can be the same as the viewport element.
   */
  scrollOffsetElement: HTMLElement;
  /**
   * The element through which you can add `scroll` events.
   * Depending on the target element it can be the same as the viewport element.
   */
  scrollEventElement: HTMLElement | Document;
  // The horizontal scrollbar's elements.
  scrollbarHorizontal: CloneableScrollbarElements;
  // The vertical scrollbar's elements.
  scrollbarVertical: CloneableScrollbarElements;
}

// The OverlayScrollbars static object.
interface OverlayScrollbarsStatic {
  // Gets the instance of the passed target or `undefined` the target has no instance.
  (target: InitializationTarget): OverlayScrollbars | undefined;
  // Initializes OverlayScrollbars to the passed target with passed options and event listeners.
  (target: InitializationTarget, options: PartialOptions, eventListeners?: EventListeners): OverlayScrollbars;
 
  // Checks whether the passed value is a valid and not destroyed overlayscrollbars instance.
  valid(osInstance: any): osInstance is OverlayScrollbars;
 
  // Gets the environment.
  env(): Environment;
 
  // Sets the nonce attribute for inline styles.
  nonce(newNonce: string | undefined): void;
 
  // Adds a single plugin.
  plugin(plugin: Plugin): InferStaticPluginModuleInstance<Plugin>
  // Adds multiple plugins.
  plugin(plugins: Plugin[]): InferStaticPluginModuleInstance<Plugin>[];
}
 
// Describes the OverlayScrollbars environment.
interface Environment {
  // The native scrollbars size of the browser / system.
  scrollbarsSize: XY<number>;
  // Whether the native scrollbars are overlaid.
  scrollbarsOverlaid: XY<boolean>;
  // Whether the browser supports native scrollbar hiding.
  scrollbarsHiding: boolean;
  // Whether the browser supports the ScrollTimeline API.
  scrollTimeline: boolean;
  // The default Initialization to use if nothing else is specified.
  staticDefaultInitialization: Initialization;
  // The default Options to use if nothing else is specified.
  staticDefaultOptions: Options;
 
  // Returns the current default Initialization.
  getDefaultInitialization(): Initialization;
  // Returns the current default Options.
  getDefaultOptions(): Options;
 
  /**
   * Sets a new default Initialization.
   * If the new default Initialization is partially filled, its deeply merged with the current default Initialization.
   * @param newDefaultInitialization The new default Initialization.
   * @returns The current default Initialization.
   */
  setDefaultInitialization(newDefaultInitialization: PartialInitialization): Initialization;
  /**
   * Sets new default Options.
   * If the new default Options are partially filled, they're deeply merged with the current default Options.
   * @param newDefaultOptions The new default Options.
   * @returns The current default options.
   */
  setDefaultOptions(newDefaultOptions: PartialOptions): Options;
}

.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;
}

// 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;
}

OverlayScrollbars(document.body, {
  scrollbars: {
    theme: 'os-theme-custom'
  }
});

<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>

const staticPlugin = {
  // Plugin has the name `examplePlugin`.
  examplePlugin: {
    // The `static` function describes a static module and returns the module instance or void / undefined if no instance is needed.
    // The `osStatic` parameter is the global `OverlayScrollbars` object.
    static: (osStatic) => {
      let count = 0;
      const staticPluginModuleInstance = {
        getCount: () => count,
        increment: () => { count++ },
      }
      return staticPluginModuleInstance;
    }
  }
}

const staticModuleInstance = OverlayScrollbars.plugin(staticPlugin); // Plugins static module is invoked
staticModuleInstance.count; // 0
staticModuleInstance.increment();
staticModuleInstance.count; // 1

const instancePlugin = {
  // Plugin has the name `examplePlugin`.
  examplePlugin: {
    // Instance function describes na instance module and returns the module instance or void / undefined if no instance is needed.
    // The `osInstance` parameter is the OverlayScrollbar instance the plugin is bound to.
    // The `event` parameter is a function which adds events to the instance which can't be removed from outside the plugin.
    // The `osStatic` parameter is the global OverlayScrollbar object.
    instance: (osInstance, event, osStatic) => {
      let count = 0;
 
      const instancePluginModuleInstance = {
        getCount: () => count,
        increment: () => { count++ },
      }
 
      // Event which fires when the instance was initialized.
      event('initialized', () => {
        console.log("instance initialized");
      });
 
      // Event which fires when the viewport was scrolled.
      const removeScrollEvent = event('scroll', () => {
        console.log("viewport scrolled");
        removeScrollEvent(); // Removes the event after the first scroll.
      });
      
      return instancePluginModuleInstance;
    }
  }
}

OverlayScrollbars.plugin(instancePlugin); // Plugin is added
 
const osInstance = OverlayScrollbars(document.body, {}); // Plugin's instance module is invoked
const instancePluginInstance = osInstance.plugin(instancePlugin);
 
instancePluginInstance.count; // 0
instancePluginInstance.increment();
instancePluginInstance.count; // 1

// Describes a OverlayScrollbar plugin.
type Plugin<
  // The name of the plugin.
  Name extends string = string,
  // The module instance type of the static module.
  S extends PluginModuleInstance | void = PluginModuleInstance | void, 
  // The module instance type of the instance module.
  I extends PluginModuleInstance | void = PluginModuleInstance | void 
> = {
  [pluginName in Name]: PluginModule<S, I>;
};
 
// Describes a OverlayScrollbar plugin which has only a static module.
type StaticPlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, T, void>;
 
// Describes a OverlayScrollbar plugin which has only a instance module.
type InstancePlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, void, T>;
 
// Infers the type of the static module's instance of the passed plugin.
type InferStaticPluginModuleInstance<T extends StaticPlugin>;
 
// Infers the type of the instance modules instance of the passed plugin.
type InferInstancePluginModuleInstance<T extends InstancePlugin>;

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

/* 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;
}