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

Static Methods

Name: tessl/npm-overlayscrollbars
Author: tessl

Global methods available on the OverlayScrollbars constructor for configuration, validation, extension management, and accessing global information.

Global Information

globals()

OverlayScrollbars.globals(): OverlayScrollbarsGlobals;

Returns global information about the plugin and browser capabilities.

Returns: Object containing global plugin state and browser support information

const globals = OverlayScrollbars.globals();

console.log(globals.defaultOptions); // Current default options
console.log(globals.supportMutationObserver); // Browser support info
console.log(globals.nativeScrollbarSize); // { x: 17, y: 17 }
console.log(globals.autoUpdateRecommended); // Whether auto-update is recommended

Default Options Management

defaultOptions()

OverlayScrollbars.defaultOptions(newOptions?: OverlayScrollbarsOptions): OverlayScrollbarsOptions;

Gets or sets the default options for all new plugin initializations.

Parameters:

newOptions (Object, optional) - New default options to merge with existing defaults

Returns: Current default options object (always returns a copy)

// Get current default options
const currentDefaults = OverlayScrollbars.defaultOptions();

// Set new default options (merged with existing)
OverlayScrollbars.defaultOptions({
  className: "os-theme-light",
  scrollbars: {
    autoHide: "leave",
    autoHideDelay: 1000
  },
  callbacks: {
    onInitialized: function() {
      console.log("OverlayScrollbars initialized");
    }
  }
});

// Future instances will inherit these defaults
const instance = OverlayScrollbars(element, {}); // Uses updated defaults

Instance Validation

valid()

OverlayScrollbars.valid(instance: any): boolean;

Checks whether the passed value is a valid, non-destroyed OverlayScrollbars instance.

Parameters:

instance (any) - Value to check for validity

Returns: true if the value is a valid OverlayScrollbars instance, false otherwise

const instance = OverlayScrollbars(element, {});

console.log(OverlayScrollbars.valid(instance)); // true
console.log(OverlayScrollbars.valid(null)); // false
console.log(OverlayScrollbars.valid({})); // false

// After destruction
instance.destroy();
console.log(OverlayScrollbars.valid(instance)); // false

Extension Management

extension()

OverlayScrollbars.extension(
  extensionName?: string,
  extension?: ExtensionConstructor | any,
  defaultOptions?: object
): OverlayScrollbarsExtension | OverlayScrollbarsExtension[] | boolean;

Registers, unregisters, or retrieves extensions.

Parameters:

extensionName (String, optional) - Name of the extension
extension (Function|any, optional) - Extension constructor function or value to unregister
defaultOptions (Object, optional) - Default options for the extension

Returns:

Extension object (when getting single extension)
Array of all extensions (when getting all)
Boolean indicating success/failure (when registering/unregistering)

// Get all registered extensions
const allExtensions = OverlayScrollbars.extension();

// Get specific extension
const myExtension = OverlayScrollbars.extension('myExtension');

// Register new extension
const success = OverlayScrollbars.extension('myExtension', function(instance, options) {
  // Extension constructor
  return {
    // Extension implementation
    added: function() {
      console.log('Extension added to instance');
    },
    removed: function() {
      console.log('Extension removed from instance');
    }
  };
}, {
  // Default options for the extension
  defaultValue: true,
  timeout: 1000
});

// Unregister extension
const removed = OverlayScrollbars.extension('myExtension', null);

Usage Examples

Setting Up Global Defaults

// Configure defaults before any initialization
OverlayScrollbars.defaultOptions({
  className: "custom-theme",
  resize: "both",
  scrollbars: {
    visibility: "auto",
    autoHide: "scroll",
    autoHideDelay: 800,
    touchSupport: true
  },
  callbacks: {
    onInitialized: function() {
      console.log('Instance initialized with defaults');
    },
    onUpdated: function() {
      console.log('Instance updated');
    }
  }
});

// All subsequent initializations inherit these defaults
const instance1 = OverlayScrollbars('.content1', {});
const instance2 = OverlayScrollbars('.content2', {
  // Only override specific options
  className: "special-theme"
});

Extension Registration Pattern

// Register a custom extension
OverlayScrollbars.extension('autoScroller', function(instance, options) {
  let intervalId;
  
  return {
    added: function() {
      if (options.enabled) {
        intervalId = setInterval(() => {
          const state = instance.getState();
          if (!state.destroyed) {
            instance.scroll({ y: '+=' + options.speed });
          }
        }, options.interval);
      }
    },
    
    removed: function() {
      if (intervalId) {
        clearInterval(intervalId);
      }
    }
  };
}, {
  // Default extension options
  enabled: false,
  speed: 10,
  interval: 100
});

// Use the extension
const instance = OverlayScrollbars(element, {}, {
  autoScroller: {
    enabled: true,
    speed: 5
  }
});

Browser Capability Detection

const globals = OverlayScrollbars.globals();

// Check browser support
if (globals.supportMutationObserver) {
  console.log('Browser supports MutationObserver');
}

if (globals.supportResizeObserver) {
  console.log('Browser supports ResizeObserver');
}

// Get native scrollbar information
const nativeSize = globals.nativeScrollbarSize;
console.log(`Native scrollbar size: ${nativeSize.x}px x ${nativeSize.y}px`);

// Check if native scrollbars are overlaid (like on macOS)
if (globals.nativeScrollbarIsOverlaid.x) {
  console.log('Native horizontal scrollbars are overlaid');
}

Types

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 OverlayScrollbarsExtension {
  added(instance: OverlayScrollbarsInstance, options: object): void;
  removed?(): void;
}

type ExtensionConstructor = (
  instance: OverlayScrollbarsInstance,
  options: object
) => OverlayScrollbarsExtension;

Install with Tessl CLI