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

Instance Methods

Name: tessl/npm-overlayscrollbars
Author: tessl

Methods available on individual OverlayScrollbars instances for controlling scrolling behavior, updating the instance, and managing the instance lifecycle.

Update Methods

update()

OverlayScrollbarsInstance.prototype.update(force?: boolean): OverlayScrollbarsInstance;

Manually updates the instance to recalculate sizes and scrollbar visibility.

Parameters:

force (Boolean, optional) - Force update even if no changes are detected

Returns: The instance for method chaining

// Standard update
instance.update();

// Force update (bypasses change detection)
instance.update(true);

// Chaining
instance.update().scroll({ y: 100 });

Scrolling Methods

scroll()

OverlayScrollbarsInstance.prototype.scroll(): ScrollPositionInfo;
OverlayScrollbarsInstance.prototype.scroll(
  coordinates: ScrollCoordinates,
  duration?: number,
  easing?: string | function,
  complete?: function
): OverlayScrollbarsInstance;

Scrolls to specified coordinates with optional animation, or returns current scroll position when called without parameters.

Parameters:

coordinates - Target scroll position (various formats supported)
duration (Number, optional) - Animation duration in milliseconds
easing (String|Function, optional) - Easing function name or custom function
complete (Function, optional) - Callback executed when scroll animation completes

Returns: The instance for method chaining (when scrolling) or scroll position information (when getting)

// Get current scroll position
const position = instance.scroll();
console.log(position.position); // { x: 100, y: 200 }
console.log(position.ratio); // { x: 0.5, y: 0.3 }
console.log(position.max); // { x: 800, y: 1200 }

// Scroll to specific coordinates
instance.scroll({ x: 100, y: 200 });

// Scroll with animation
instance.scroll({ y: 500 }, 1000, 'easeOutQuart');

// Scroll to element
instance.scroll(document.querySelector('.target-element'));

// Scroll to bottom
instance.scroll({ y: '100%' });

// Scroll with completion callback
instance.scroll({ x: 0, y: 0 }, 800, 'swing', function() {
  console.log('Scrolled to top');
});

// Various coordinate formats
instance.scroll(100); // Scroll to x: 100
instance.scroll('50%'); // Scroll to 50% of content
instance.scroll({ y: 'begin' }); // Scroll to beginning
instance.scroll({ y: 'end' }); // Scroll to end

scrollStop()

OverlayScrollbarsInstance.prototype.scrollStop(): OverlayScrollbarsInstance;

Stops all currently running scroll animations.

Returns: The instance for method chaining

// Stop any running scroll animations
instance.scrollStop();

// Can be chained with other methods
instance.scrollStop().scroll({ y: 0 });

Options Management

options()

OverlayScrollbarsInstance.prototype.options(
  newOptions?: OverlayScrollbarsOptions | string,
  value?: any
): OverlayScrollbarsOptions | OverlayScrollbarsInstance;

Gets current options or updates instance options.

Parameters:

newOptions (Object|String, optional) - New options object or property name
value (any, optional) - Value when setting single property

Returns: Current options object (getter) or instance for chaining (setter)

// Get all current options
const currentOptions = instance.options();

// Set multiple options
instance.options({
  className: "new-theme",
  scrollbars: {
    autoHide: "scroll",
    autoHideDelay: 500
  }
});

// Set single option by property path
instance.options('scrollbars.autoHide', 'leave');
instance.options('className', 'custom-theme');

// Nested property setting
instance.options('callbacks.onScrollStart', function() {
  console.log('Scroll started');
});

Lifecycle Methods

destroy()

OverlayScrollbarsInstance.prototype.destroy(): OverlayScrollbarsInstance;

Destroys the instance and restores the original element to its initial state.

Returns: The destroyed instance

// Destroy instance and clean up
instance.destroy();

// Check if instance is destroyed
if (instance.getState().destroyed) {
  console.log('Instance has been destroyed');
}

sleep()

OverlayScrollbarsInstance.prototype.sleep(): OverlayScrollbarsInstance;

Puts the instance to sleep, disabling automatic update detection.

Returns: The instance for method chaining

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

// Wake up by manually updating
instance.update();

// Check sleep state
const isSleeping = instance.getState('sleeping');

State and Element Access

getState()

OverlayScrollbarsInstance.prototype.getState(property?: string): OverlayScrollbarsState | any;

Gets current state information about the instance.

Parameters:

property (String, optional) - Specific state property to retrieve

Returns: Complete state object or specific property value

getElements()

OverlayScrollbarsInstance.prototype.getElements(elementName?: string): OverlayScrollbarsElements | Element;

Gets internal DOM elements created and managed by the instance.

Parameters:

elementName (String, optional) - Specific element name to retrieve

Returns: Complete elements object or specific element

// Get current scroll position from state
const state = instance.getState();
console.log(state.contentScrollSize); // { width: 1200, height: 800 }
console.log(state.hasOverflow); // { x: true, y: false }

// Get specific state property
const hasXOverflow = instance.getState('hasOverflow').x;

// Get all internal elements
const elements = instance.getElements();
const viewport = elements.viewport;

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

Extension Management

ext()

OverlayScrollbarsInstance.prototype.ext(extensionName?: string): OverlayScrollbarsExtension | OverlayScrollbarsExtension[] | undefined;

Gets extension instance(s) that have been added to this OverlayScrollbars instance.

Parameters:

extensionName (String, optional) - Name of specific extension to retrieve

Returns: Extension instance, array of all extensions, or undefined if not found

// Get all extensions added to this instance
const allExtensions = instance.ext();

// Get specific extension
const myExtension = instance.ext('myExtension');
if (myExtension) {
  // Use extension-specific methods
  myExtension.customMethod();
}

addExt()

OverlayScrollbarsInstance.prototype.addExt(
  extensionName: string,
  extensionOptions?: object
): OverlayScrollbarsExtension | undefined;

Adds an extension to this specific instance.

Parameters:

extensionName (String) - Name of the registered extension to add
extensionOptions (Object, optional) - Options for the extension instance

Returns: The added extension instance or undefined if the extension couldn't be added

// Add extension with default options
const extension = instance.addExt('myExtension');

// Add extension with custom options
const extension = instance.addExt('autoScroller', {
  enabled: true,
  speed: 5,
  interval: 200
});

if (extension) {
  console.log('Extension added successfully');
}

removeExt()

OverlayScrollbarsInstance.prototype.removeExt(extensionName: string): boolean;

Removes an extension from this specific instance.

Parameters:

extensionName (String) - Name of the extension to remove

Returns: true if the extension was removed, false if it wasn't found

// Remove specific extension
const removed = instance.removeExt('myExtension');
if (removed) {
  console.log('Extension removed successfully');
}

// Extension cleanup is handled automatically

Method Chaining Examples

// Chain multiple operations
instance
  .update(true)
  .scroll({ y: 0 }, 500)
  .options('scrollbars.autoHide', 'leave');

// Update options and scroll
instance
  .options({
    scrollbars: { autoHideDelay: 200 }
  })
  .sleep()
  .update()
  .scroll({ x: '50%', y: '50%' }, 1000, 'easeInOutQuad');

// Extension management with chaining
instance
  .addExt('customExtension', { option: true })
  .update()
  .scroll({ y: 100 });

Types

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

interface ScrollPositionInfo {
  position: { x: number; y: number };
  ratio: { x: number; y: number };
  max: { x: number; y: number };
}

interface ScrollPosition {
  x: number;
  y: number;
}

type EasingFunction = (t: number, b: number, c: number, d: number) => number;

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