or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

extensions.mdindex.mdinitialization.mdinstance-methods.mdjquery.mdoptions.mdstatic-methods.md
tile.json

tessl/npm-overlayscrollbars

A javascript scrollbar plugin which hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/overlayscrollbars@1.13.x

To install, run

npx @tessl/cli install tessl/npm-overlayscrollbars@1.13.0

index.mddocs/

OverlayScrollbars

OverlayScrollbars is a JavaScript scrollbar plugin that hides native scrollbars and provides custom, styleable overlay scrollbars while maintaining native functionality and feeling. It supports both vanilla JavaScript and jQuery implementations with extensive browser compatibility (IE8+), automatic update detection, powerful scroll animations, and a rich extension system.

Package Information

  • Package Name: overlayscrollbars
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install overlayscrollbars

Core Imports

ES Modules:

import OverlayScrollbars from "overlayscrollbars";

CommonJS:

const OverlayScrollbars = require("overlayscrollbars");

UMD (Browser Global):

<script src="node_modules/overlayscrollbars/js/OverlayScrollbars.min.js"></script>
<link rel="stylesheet" href="node_modules/overlayscrollbars/css/OverlayScrollbars.min.css">
<script>
// OverlayScrollbars is available globally
</script>

jQuery Plugin:

import "overlayscrollbars/js/jquery.overlayScrollbars.min.js";
// or
<script src="overlayscrollbars/js/jquery.overlayScrollbars.min.js"></script>

Basic Usage

import OverlayScrollbars from "overlayscrollbars";

// Initialize on a single element
const osInstance = OverlayScrollbars(document.querySelector('.content'), {
  className: "os-theme-dark",
  scrollbars: {
    autoHide: "leave"
  }
});

// Initialize on multiple elements
const instances = OverlayScrollbars(document.querySelectorAll('.scrollable'), {
  resize: "both",
  scrollbars: {
    visibility: "auto",
    autoHide: "scroll"
  }
});

// jQuery usage
$('.content').overlayScrollbars({
  className: "os-theme-dark",
  callbacks: {
    onScrollStart: function() {
      console.log("Scrolling started");
    }
  }
});

Architecture

OverlayScrollbars is built around several key components:

  • Constructor Function: Main OverlayScrollbars() function for creating instances
  • Instance Methods: Methods for controlling and querying individual scrollbar instances
  • Static Methods: Global configuration and utility methods (globals(), defaultOptions(), etc.)
  • Options System: Comprehensive configuration object with nested options for different aspects
  • Extension System: Plugin architecture for extending functionality
  • jQuery Integration: Seamless jQuery plugin interface
  • Event System: Comprehensive callback system for lifecycle and scroll events

Capabilities

Core Initialization and Management

Primary constructor and instance management functionality for creating, configuring, and controlling OverlayScrollbars instances.

function OverlayScrollbars(
  target: Element | NodeList | string,
  options?: OverlayScrollbarsOptions,
  extensions?: OverlayScrollbarsExtensions
): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];

Initialization and Management

Instance Control Methods

Instance methods for updating, scrolling, controlling behavior, and managing extensions on individual OverlayScrollbars instances.

interface OverlayScrollbarsInstance {
  update(force?: boolean): OverlayScrollbarsInstance;
  scroll(coordinates: ScrollCoordinates, duration?: number, easing?: string | function, complete?: function): OverlayScrollbarsInstance;
  scrollStop(): OverlayScrollbarsInstance;
  destroy(): OverlayScrollbarsInstance;
  ext(extensionName?: string): OverlayScrollbarsExtension | OverlayScrollbarsExtension[] | undefined;
  addExt(extensionName: string, extensionOptions?: object): OverlayScrollbarsExtension | undefined;
  removeExt(extensionName: string): boolean;
}

Instance Methods

Static Configuration Methods

Global methods for configuring default options, validating instances, and managing extensions across all OverlayScrollbars instances.

interface OverlayScrollbarsStatic {
  globals(): OverlayScrollbarsGlobals;
  defaultOptions(newOptions?: OverlayScrollbarsOptions): OverlayScrollbarsOptions;
  valid(instance: any): boolean;
  extension(name: string, extension?: function, defaultOptions?: object): any;
}

Static Methods

Configuration Options

Comprehensive configuration system with nested options for scrollbar behavior, appearance, callbacks, and specialized functionality.

interface OverlayScrollbarsOptions {
  className?: string | null;
  resize?: "none" | "both" | "horizontal" | "vertical";
  sizeAutoCapable?: boolean;
  scrollbars?: ScrollbarsOptions;
  overflowBehavior?: OverflowBehaviorOptions;
  callbacks?: CallbackOptions;
}

Configuration Options

Extension System

Plugin architecture for extending OverlayScrollbars functionality with custom extensions that can be registered globally and used across instances.

interface OverlayScrollbarsExtension {
  added(instance: OverlayScrollbarsInstance): void;
  removed?(): void;
}

Extensions

jQuery Integration

jQuery plugin interface providing seamless integration with jQuery selectors and chaining while maintaining full API compatibility.

interface JQuery {
  overlayScrollbars(options: OverlayScrollbarsOptions, extensions?: OverlayScrollbarsExtensions): JQuery;
  overlayScrollbars(): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
}

jQuery Integration

Types

type ScrollCoordinates = {
  x?: number | string;
  y?: number | string;
} | number | string | Element;

interface OverlayScrollbarsGlobals {
  defaultOptions: OverlayScrollbarsOptions;
  autoUpdateRecommended: boolean;
  supportMutationObserver: boolean;
  supportResizeObserver: boolean;
  supportPassiveEvents: boolean;
  supportTransform: boolean;
  supportTransition: boolean;
  restrictedMeasuring: boolean;
  nativeScrollbarStyling: boolean;
  cssCalc: string | null;
  nativeScrollbarSize: { x: number; y: number };
  nativeScrollbarIsOverlaid: { x: boolean; y: boolean };
  overlayScrollbarDummySize: { x: number; y: number };
  rtlScrollBehavior: { i: boolean; n: boolean };
}

interface ScrollbarsOptions {
  visibility?: "visible" | "hidden" | "auto";
  autoHide?: "never" | "scroll" | "leave" | "move";
  autoHideDelay?: number;
  dragScrolling?: boolean;
  clickScrolling?: boolean;
  touchSupport?: boolean;
  snapHandle?: boolean;
}

interface OverflowBehaviorOptions {
  x?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
  y?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
}

interface CallbackOptions {
  onInitialized?: (instance: OverlayScrollbarsInstance) => void;
  onInitializationWithdrawn?: (instance: OverlayScrollbarsInstance) => void;
  onDestroyed?: (instance: OverlayScrollbarsInstance) => void;
  onScrollStart?: (instance: OverlayScrollbarsInstance) => void;
  onScroll?: (instance: OverlayScrollbarsInstance) => void;
  onScrollStop?: (instance: OverlayScrollbarsInstance) => void;
  onOverflowChanged?: (instance: OverlayScrollbarsInstance) => void;
  onOverflowAmountChanged?: (instance: OverlayScrollbarsInstance) => void;
  onDirectionChanged?: (instance: OverlayScrollbarsInstance) => void;
  onContentSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
  onHostSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
  onUpdated?: (instance: OverlayScrollbarsInstance) => void;
}

type OverlayScrollbarsExtensions = object | object[];