or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-management.mdindex.mdinstance-control.mdmomentum-control.mdplugin-system.md
tile.json

tessl/npm-smooth-scrollbar

Customize scrollbar in modern browsers with smooth scrolling experience.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/smooth-scrollbar@8.8.x

To install, run

npx @tessl/cli install tessl/npm-smooth-scrollbar@8.8.0

index.mddocs/

Smooth Scrollbar

Smooth Scrollbar is a customizable, flexible, and high-performance scrollbar library for modern browsers that enables developers to replace native scrollbars with smooth-scrolling custom implementations. It offers extensive customization options through CSS styling, plugin system support, and comprehensive APIs for controlling scrolling behavior, momentum, and overscroll effects.

Package Information

  • Package Name: smooth-scrollbar
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install smooth-scrollbar

Core Imports

import Scrollbar from "smooth-scrollbar";

For CommonJS:

const Scrollbar = require("smooth-scrollbar");

UMD (browser):

<script src="dist/smooth-scrollbar.js"></script>

Basic Usage

import Scrollbar from "smooth-scrollbar";

// Initialize scrollbar on a DOM element
const container = document.querySelector("#my-scrollbar");
const scrollbar = Scrollbar.init(container, {
  damping: 0.1,
  thumbMinSize: 20,
  renderByPixels: true,
  alwaysShowTracks: false,
  continuousScrolling: true
});

// Initialize on all elements with data-scrollbar attribute
const scrollbars = Scrollbar.initAll();

// Listen to scroll events
scrollbar.addListener((status) => {
  console.log(`Scroll position: x=${status.offset.x}, y=${status.offset.y}`);
});

// Programmatic scrolling
scrollbar.scrollTo(0, 100, 300); // x, y, duration in ms

Architecture

Smooth Scrollbar is built around several key components:

  • Main Scrollbar Class: Core functionality with lifecycle management and event handling
  • Track System: Visual scrollbar tracks and thumbs with automatic sizing and positioning
  • Options System: Comprehensive configuration with validation decorators
  • Plugin Architecture: Extensible plugin system with lifecycle hooks for custom functionality
  • Event Handling: Touch, mouse, wheel, and keyboard event processing for smooth scrolling
  • Momentum Engine: Physics-based momentum calculation for natural scrolling feel

Capabilities

Core Scrollbar Management

Primary interface for creating, managing, and destroying scrollbar instances. Provides both single-element and batch operations.

class SmoothScrollbar {
  static version: string;
  static ScrollbarPlugin: typeof ScrollbarPlugin;
  
  static init(elem: HTMLElement, options?: Partial<ScrollbarOptions>): Scrollbar;
  static initAll(options?: Partial<ScrollbarOptions>): Scrollbar[];
  static has(elem: HTMLElement): boolean;
  static get(elem: HTMLElement): Scrollbar | undefined;
  static getAll(): Scrollbar[];
  static destroy(elem: HTMLElement): void;
  static destroyAll(): void;
  static use(...Plugins: (typeof ScrollbarPlugin)[]): void;
  static attachStyle(): void;
  static detachStyle(): void;
}

Core Management

Scrollbar Instance Control

Individual scrollbar instance methods for precise control over scrolling behavior, position, and state.

interface Scrollbar {
  readonly containerEl: HTMLElement;
  readonly contentEl: HTMLElement;
  readonly options: ScrollbarOptions;
  readonly size: ScrollbarSize;
  readonly offset: Data2d;
  readonly limit: Data2d;
  scrollTop: number;
  scrollLeft: number;
  
  destroy(): void;
  update(): void;
  scrollTo(x?: number, y?: number, duration?: number, options?: Partial<ScrollToOptions>): void;
  setPosition(x?: number, y?: number, options?: Partial<SetPositionOptions>): void;
  scrollIntoView(elem: HTMLElement, options?: Partial<ScrollIntoViewOptions>): void;
  addListener(fn: ScrollListener): void;
  removeListener(fn: ScrollListener): void;
}

Instance Control

Plugin System

Extensible plugin architecture for adding custom behaviors like overscroll effects, custom easing, or specialized scrolling modes.

class ScrollbarPlugin {
  static pluginName: string;
  static defaultOptions: any;
  
  readonly scrollbar: Scrollbar;
  readonly options: any;
  readonly name: string;
  
  onInit(): void;
  onDestroy(): void;
  onUpdate(): void;
  onRender(remainMomentum: Data2d): void;
  transformDelta(delta: Data2d, evt: Event): Data2d;
}

Plugin System

Momentum and Physics

Advanced momentum control for natural scrolling physics with customizable easing and momentum manipulation.

interface Scrollbar {
  addMomentum(x: number, y: number): void;
  setMomentum(x: number, y: number): void;
  addTransformableMomentum(
    x: number, 
    y: number, 
    fromEvent: Event, 
    callback?: AddTransformableMomentumCallback
  ): void;
}

interface AddTransformableMomentumCallback {
  (this: Scrollbar, willScroll: boolean): void;
}

Momentum Control

Configuration Types

interface ScrollbarOptions {
  damping: number;
  thumbMinSize: number;
  renderByPixels: boolean;
  alwaysShowTracks: boolean;
  continuousScrolling: boolean;
  delegateTo: EventTarget | null;
  wheelEventTarget: EventTarget | null; // deprecated
  plugins: any;
}

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

interface ScrollbarSize {
  container: Metrics;
  content: Metrics;
}

interface Metrics {
  width: number;
  height: number;
}

interface ScrollStatus {
  offset: Data2d;
  limit: Data2d;
}

interface ScrollListener {
  (this: Scrollbar, status: ScrollStatus): void;
}

interface TrackController {
  readonly xAxis: ScrollbarTrack;
  readonly yAxis: ScrollbarTrack;
  update(): void;
  autoHideOnIdle(): void;
}

interface ScrollbarTrack {
  readonly element: HTMLElement;
  readonly thumb: ScrollbarThumb;
  show(): void;
  hide(): void;
  update(offset: number, containerSize: number, contentSize: number): void;
  attachTo(element: HTMLElement): void;
}

interface ScrollbarThumb {
  readonly element: HTMLElement;
  displaySize: number;
  realSize: number;
  offset: number;
  attachTo(track: HTMLElement): void;
  update(scrollOffset: number, containerSize: number, pageSize: number): void;
}