tessl/npm-smooth-scrollbar

Customize scrollbar in modern browsers with smooth scrolling experience.

—

Pending

Overview

Eval results

Files

Scrollbar Instance Control

Name: tessl/npm-smooth-scrollbar
Author: tessl

Individual scrollbar instance methods for precise control over scrolling behavior, position, and state. Each scrollbar instance provides comprehensive access to scrolling operations and state management.

Capabilities

Scrollbar Properties

Core properties providing access to scrollbar state and DOM elements.

interface Scrollbar {
  /** Parent scrollbar reference for nested scrollbars */
  readonly parent: Scrollbar | null;
  
  /** Container DOM element */
  readonly containerEl: HTMLElement;
  
  /** Content DOM element inside container */
  readonly contentEl: HTMLElement;
  
  /** Track controller managing visual scrollbar tracks */
  readonly track: TrackController;
  
  /** Current configuration options */
  readonly options: ScrollbarOptions;
  
  /** Bounding box information */
  bounding: ScrollbarBounding;
  
  /** Size metrics for container and content */
  size: ScrollbarSize;
  
  /** Current scroll offset position */
  offset: Data2d;
  
  /** Maximum scroll limits */
  limit: Data2d;
  
  /** Vertical scroll position (alias for offset.y) */
  scrollTop: number;
  
  /** Horizontal scroll position (alias for offset.x) */
  scrollLeft: number;
}

Lifecycle Management

Methods for managing the scrollbar instance lifecycle.

/**
 * Destroys the scrollbar instance and cleans up all resources
 */
destroy(): void;

/**
 * Updates scrollbar state and recalculates dimensions
 */
update(): void;

Usage Examples:

// Force update after DOM changes
scrollbar.update();

// Clean up when element is removed
scrollbar.destroy();

Size and Visibility

Methods for querying scrollbar dimensions and element visibility.

/**
 * Gets current size metrics for container and content
 * @returns Size information including container and content dimensions
 */
getSize(): ScrollbarSize;

/**
 * Checks if an element is visible within the scrollable area
 * @param elem - DOM element to check visibility for
 * @returns True if element is currently visible
 */
isVisible(elem: HTMLElement): boolean;

Usage Examples:

// Check if element needs scrolling
const targetElement = document.querySelector("#target");
if (!scrollbar.isVisible(targetElement)) {
  scrollbar.scrollIntoView(targetElement);
}

// Get current dimensions
const size = scrollbar.getSize();
console.log(`Container: ${size.container.width}x${size.container.height}`);
console.log(`Content: ${size.content.width}x${size.content.height}`);

Scroll Positioning

Methods for controlling scroll position with various options and animations.

/**
 * Scrolls to specified position with optional animation
 * @param x - Horizontal position (optional)
 * @param y - Vertical position (optional)  
 * @param duration - Animation duration in milliseconds (optional)
 * @param options - Additional scrolling options (optional)
 */
scrollTo(x?: number, y?: number, duration?: number, options?: Partial<ScrollToOptions>): void;

/**
 * Sets scroll position immediately without animation
 * @param x - Horizontal position (optional)
 * @param y - Vertical position (optional)
 * @param options - Position setting options (optional)
 */
setPosition(x?: number, y?: number, options?: Partial<SetPositionOptions>): void;

/**
 * Scrolls an element into view with alignment options
 * @param elem - DOM element to scroll into view
 * @param options - Scroll into view configuration (optional)
 */
scrollIntoView(elem: HTMLElement, options?: Partial<ScrollIntoViewOptions>): void;

Usage Examples:

// Smooth scroll to top
scrollbar.scrollTo(0, 0, 800);

// Instant positioning
scrollbar.setPosition(100, 200);

// Scroll element into view
const element = document.querySelector("#section-3");
scrollbar.scrollIntoView(element, {
  alignToTop: true,
  offsetTop: 20
});

// Custom easing and callback
scrollbar.scrollTo(0, 500, 1000, {
  easing: (t) => t * t, // quadratic easing
  callback() {
    console.log("Scroll completed!");
  }
});

Event Listeners

Methods for managing scroll event listeners.

/**
 * Adds a scroll event listener
 * @param fn - Listener function to add
 */
addListener(fn: ScrollListener): void;

/**
 * Removes a scroll event listener
 * @param fn - Listener function to remove
 */
removeListener(fn: ScrollListener): void;

Usage Examples:

// Add scroll listener
const handleScroll = (status) => {
  const { offset, limit } = status;
  const scrollPercent = {
    x: (offset.x / limit.x) * 100,
    y: (offset.y / limit.y) * 100
  };
  console.log(`Scroll progress: ${scrollPercent.y.toFixed(1)}%`);
};

scrollbar.addListener(handleScroll);

// Remove listener when done
scrollbar.removeListener(handleScroll);

Plugin Management

Methods for managing plugin options on individual scrollbar instances.

/**
 * Updates options for a specific plugin
 * @param pluginName - Name of the plugin to update
 * @param options - New options for the plugin
 */
updatePluginOptions(pluginName: string, options?: any): void;

Usage Examples:

// Update overscroll plugin options
scrollbar.updatePluginOptions("overscroll", {
  effect: "glow",
  glowColor: "#ff6b6b",
  maxOverscroll: 200
});

Configuration Types

interface ScrollToOptions {
  /** Callback function called when scroll completes */
  callback: (this: Scrollbar) => void;
  
  /** Easing function for scroll animation */
  easing: (percent: number) => number;
}

interface SetPositionOptions {
  /** Skip calling scroll listeners during position change */
  withoutCallbacks: boolean;
}

interface ScrollIntoViewOptions {
  /** Align element to top of viewport */
  alignToTop: boolean;
  
  /** Only scroll if element is not already visible */
  onlyScrollIfNeeded: boolean;
  
  /** Additional top offset */
  offsetTop: number;
  
  /** Additional left offset */
  offsetLeft: number;
  
  /** Additional bottom offset */
  offsetBottom: number;
}

interface ScrollbarBounding {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

Install with Tessl CLI