tessl/npm-overlayscrollbars

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Initialization and Management

Name: tessl/npm-overlayscrollbars
Author: tessl

Core functionality for creating and managing OverlayScrollbars instances, including constructor usage patterns and instance lifecycle management.

Constructor

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

Parameters:

target - Element(s) to apply scrollbars to. Can be a single Element, NodeList, or selector string
options - Configuration options object (optional)
extensions - Extensions to initialize with the instance (optional)

Returns: Single instance for single elements, array of instances for multiple elements

Usage Examples

Single Element Initialization

// Initialize with minimal options
const instance = OverlayScrollbars(document.querySelector('.content'), {});

// Initialize with configuration
const instance = OverlayScrollbars(document.getElementById('main'), {
  className: "os-theme-dark",
  resize: "both",
  scrollbars: {
    autoHide: "leave",
    autoHideDelay: 1000
  }
});

Multiple Elements Initialization

// Initialize multiple elements with same options
const instances = OverlayScrollbars(document.querySelectorAll('.scrollable'), {
  scrollbars: {
    visibility: "auto"
  }
});

// Access individual instances
instances.forEach((instance, index) => {
  console.log(`Instance ${index} initialized`);
});

Query-based Initialization

// Using selector strings
const instances = OverlayScrollbars('.content, .sidebar', {
  className: "custom-theme"
});

With Extensions

const instance = OverlayScrollbars(element, {
  scrollbars: { autoHide: "scroll" }
}, {
  // Extension configuration
  customExtension: { option: true }
});

Instance Retrieval

You can retrieve existing instances without reinitializing:

// Get existing instance (returns undefined if not initialized)
const existingInstance = OverlayScrollbars(element);

// Get multiple existing instances
const existingInstances = OverlayScrollbars(document.querySelectorAll('.content'));

Conditional Initialization

// Initialize only elements that match condition
const instances = OverlayScrollbars(document.querySelectorAll('.content'), '!');
// Returns only valid, non-destroyed instances

// Initialize with custom condition function
const instances = OverlayScrollbars(
  document.querySelectorAll('.content'),
  (element, existingInstance) => {
    // Return true to include this element
    return element.scrollHeight > element.clientHeight;
  }
);

Instance State Management

interface OverlayScrollbarsInstance {
  getState(property?: string): OverlayScrollbarsState | any;
  getElements(elementName?: string): OverlayScrollbarsElements | Element;
}

Getting Instance State

const instance = OverlayScrollbars(element, {});

// Get complete state
const state = instance.getState();
console.log(state.destroyed); // false
console.log(state.sleeping); // false
console.log(state.autoUpdate); // auto-update status

// Get specific state property
const isDestroyed = instance.getState('destroyed');

Getting Instance Elements

// Get all internal elements
const elements = instance.getElements();
console.log(elements.target); // Original target element
console.log(elements.host); // Host wrapper element
console.log(elements.viewport); // Viewport element
console.log(elements.content); // Content wrapper element

// Get specific element
const viewport = instance.getElements('viewport');

Sleep Mode

Put instances to sleep to disable automatic updates:

OverlayScrollbarsInstance.prototype.sleep(): OverlayScrollbarsInstance;

// Put instance to sleep (disables auto-updates)
instance.sleep();

// Wake up with manual update
instance.update();

Types

interface OverlayScrollbarsState {
  destroyed: boolean;
  sleeping: boolean;
  autoUpdate: boolean | null;
  widthAuto: boolean;
  heightAuto: boolean;
  padding: { t: number; r: number; b: number; l: number };
  overflowAmount: { x: number; y: number };
  hideOverflow: { x: boolean; y: boolean };
  hasOverflow: { x: boolean; y: boolean };
  contentScrollSize: { width: number; height: number };
  viewportSize: { width: number; height: number };
  hostSize: { width: number; height: number };
}

interface OverlayScrollbarsElements {
  target: Element;
  host: Element;
  padding: Element;
  viewport: Element;
  content: Element;
  scrollbarHorizontal: { scrollbar: Element; track: Element; handle: Element };
  scrollbarVertical: { scrollbar: Element; track: Element; handle: Element };
  scrollbarCorner: Element;
}

Install with Tessl CLI