Class Scrollbar

Custom scrollbar for window, HTMLElement, and Snap containers.

  • Hides the native scrollbar on the scroll target and renders track/thumb DOM
  • Syncs thumb position on scroll (scroll or Snap update)
  • Optional thumb drag via Swipe when draggable is enabled
  • Auto-sizes the thumb and reacts to content/container resize
  • autoHide fades the bar in on scroll and out after inactivity

One instance controls a single axis. Use separate instances for x and y.

Documentation

Hierarchy (View Summary)

Constructors

Accessors

  • get axis(): "x" | "y"

    Scroll axis

    Returns "x" | "y"

  • get container(): Window | HTMLElement | Snap

    The element to which the scrollbar is applied

    Returns Window | HTMLElement | Snap

  • get isDestroyed(): boolean

    Indicates whether the instance has been destroyed.

    After destruction, destroy is a no-op.

    Returns boolean

  • get name(): string

    The name of the module, derived from the class name

    Returns string

  • get outer(): HTMLElement

    Scrollbar outer element

    Returns HTMLElement

  • get parent(): HTMLElement

    The element where the scrollbar is appended. If parent is not set, it defaults to container or document.body (if applied to window).

    Returns HTMLElement

  • get prefix(): string

    Optional prefix for classnames used by the module

    Returns string

  • get scrollableSize(): number

    Returns the total scrollable distance.

    Returns number

  • get scrollElement(): HTMLElement | Snap

    The actual scrollable element. Returns document.documentElement for window, otherwise the container itself.

    Returns HTMLElement | Snap

  • get scrollSize(): number

    Returns the total scroll width/height of the content.

    Returns number

  • get scrollValue(): number

    Returns scrollTop or scrollLeft of the scrollable element.

    Returns number

  • get thumb(): HTMLElement

    Scrollbar thumb element (draggable handle)

    Returns HTMLElement

  • get thumbSize(): number

    Returns the current thumb size.

    Returns number

  • get track(): HTMLElement

    Scrollbar track element (the container of the thumb)

    Returns HTMLElement

  • get trackSize(): number

    Returns the current track size.

    Returns number

Methods

  • Adds prefixed classes to an element and removes them on destroy.

    Skips classes that are already present on the element.

    Parameters

    • element: Element

      Target DOM element.

    • ...classes: string[]

      Unprefixed class name segments.

    Returns void

  • Builds one or more prefixed class names.

    Parameters

    • ...classes: string[]

      Unprefixed class name segments.

    Returns string

    Space-separated prefixed class string.

  • Internal method to handle the destruction of the module. It removes all callbacks, destroys properties, and cleans up event listeners and class names.

    Returns void

  • Set default mutable props

    Returns { __mutableProp: true; autoSize: boolean; minSize: string | number }

    • __mutableProp: true
    • autoSize: boolean

      Enables automatic adjustment of the scrollbar size.

      true
      
    • minSize: string | number

      Minimum size of the scrollbar thumb. Accepts numeric values (interpreted as pixels) or CSS units (px, rem, vw, vh, svh).

      50
      
  • Get default static props

    Returns {
        __staticProp: true;
        autoHide: boolean;
        axis: "x" | "y";
        class: string | false;
        container: Window | HTMLElement | Snap;
        draggable: boolean;
        parent: false | HTMLElement;
        resizeDebounce: number;
    }

    • __staticProp: true
    • autoHide: boolean

      Automatically hides the scrollbar when inactive.

      true
      
    • axis: "x" | "y"

      Defines the scrolling axis for the scrollbar.

      • 'x' for horizontal scrolling.
      • 'y' for vertical scrolling.
      'y'
      
    • class: string | false

      Custom CSS class to be applied to the scrollbar track. If false, no additional class is applied.

      false
      
    • container: Window | HTMLElement | Snap

      The element to which the scrollbar is applied. Can be either the window or a specific HTML element.

      window
      
    • draggable: boolean

      Determines whether the scrollbar thumb is draggable.

      true
      
    • parent: false | HTMLElement

      The parent element where the scrollbar should be appended. If false, the scrollbar is appended directly to the container. For proper behavior, use parent when applying the scrollbar to an HTML element.

      false
      
    • resizeDebounce: number

      Debounce time (in milliseconds) for handling resize events. Helps improve performance by limiting the frequency of resize calculations.

      50
      
  • Destroys the instance and runs all registered cleanup actions.

    Safe to call multiple times; subsequent calls are ignored.

    Execution order:

    1. _destroy
    2. all onDestroy callbacks, in registration order
    3. isDestroyed is set to true

    Returns void

  • Registers a function to run when the instance is destroyed.

    If the instance is already destroyed, action runs immediately.

    Parameters

    • action: () => void

      Cleanup function (for example remove listeners or DOM classes).

    Returns void

  • Resize the scrollbar.

    Returns void