or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-scrolling.mdevents.mdfeatures.mdindex.md
tile.json

tessl/npm-better-scroll

High-performance mobile scrolling library with smooth scrolling, momentum, bounce effects, and extensive plugin support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/better-scroll@1.15.x

To install, run

npx @tessl/cli install tessl/npm-better-scroll@1.15.0

index.mddocs/

Better Scroll

Better Scroll is a high-performance mobile scrolling library implemented in pure JavaScript that provides smooth scrolling capabilities for mobile web applications. The library is inspired by iScroll but offers better performance and additional features including snap scrolling, wheel picker, pull-to-refresh, infinite scrolling, zoom functionality, and scrollbar customization.

Package Information

  • Package Name: better-scroll
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install better-scroll
  • Size: 63KB compiled, 35KB compressed, 9KB gzipped
  • Dependencies: None (dependency-free)

Core Imports

import BScroll from "better-scroll";

For CommonJS:

const BScroll = require("better-scroll");

For UMD (browser):

<script src="node_modules/better-scroll/dist/bscroll.js"></script>
<!-- BScroll is now available as a global variable -->

Basic Usage

import BScroll from "better-scroll";

// HTML structure required:
// <div class="wrapper">
//   <ul class="content">
//     <li>Item 1</li>
//     <li>Item 2</li>
//     <!-- more items -->
//   </ul>
// </div>

// Basic initialization
const wrapper = document.querySelector('.wrapper');
const scroll = new BScroll(wrapper);

// With options
const scroll = new BScroll('.wrapper', {
  scrollY: true,
  scrollX: false,
  momentum: true,
  bounce: true,
  probeType: 2,
  click: true
});

// Listen to scroll events
scroll.on('scroll', (position) => {
  console.log('Current position:', position.x, position.y);
});

// Programmatic scrolling
scroll.scrollTo(0, -100, 300); // x, y, duration
scroll.scrollToElement('.target-element', 300);

Architecture

Better Scroll uses a mixin-based architecture where functionality is composed from multiple mixins:

  • Core System: Basic scrolling mechanics, event handling, and DOM manipulation
  • Feature Mixins: Modular plugins that extend core functionality (snap, wheel, zoom, etc.)
  • Event System: Custom event emitter for scroll lifecycle and user interaction events
  • Configuration System: Extensive options system with smart defaults and feature detection

The library only handles scrolling for the first child element of the wrapper container.

Capabilities

Core Scrolling

Essential scrolling functionality including momentum, bounce effects, and programmatic control. Handles both touch and mouse interactions with configurable behavior.

class BScroll {
  constructor(el: string | HTMLElement, options?: BScrollOptions);
  
  // Position control
  scrollTo(x: number, y: number, time?: number, easing?: EasingFunction): void;
  scrollBy(x: number, y: number, time?: number, easing?: EasingFunction): void;
  scrollToElement(el: HTMLElement | string, time?: number, offsetX?: number | boolean, offsetY?: number | boolean, easing?: EasingFunction): void;
  
  // State management
  refresh(): void;
  enable(): void;
  disable(): void;
  stop(): void;
  destroy(): void;
  
  // Position queries
  getComputedPosition(): {x: number, y: number};
}

interface BScrollOptions {
  startX?: number;
  startY?: number;
  scrollX?: boolean;
  scrollY?: boolean;
  freeScroll?: boolean;
  momentum?: boolean;
  bounce?: boolean | BounceOptions;
  probeType?: number;
  click?: boolean;
  preventDefault?: boolean;
  // ... many more options
}

interface BounceOptions {
  top?: boolean;
  bottom?: boolean;
  left?: boolean;
  right?: boolean;
}

Core Scrolling

Event System

Comprehensive event system for tracking scroll state, user interactions, and lifecycle events with custom event emitter pattern.

// Event management
on(type: string, fn: Function, context?: any): void;
once(type: string, fn: Function, context?: any): void;
off(type: string, fn: Function): void;

// Core events fired:
// 'scroll' - During scrolling with {x, y} position
// 'scrollStart' - When scrolling begins
// 'scrollEnd' - When scrolling ends with {x, y} position
// 'beforeScrollStart' - Before scroll starts
// 'touchEnd' - On touch/mouse up with {x, y} position
// 'flick' - On quick flick gesture
// 'refresh' - After refresh() call

Events

Snap/Slide Feature

Page-based scrolling with snap-to-position functionality. Ideal for carousels, image galleries, and paged content with smooth transitions between discrete positions.

interface SnapOptions {
  loop?: boolean;
  threshold?: number;
  speed?: number;
  easing?: EasingFunction;
  stepX?: number;
  stepY?: number;
  el?: HTMLElement | string;
}

// Instance properties when snap enabled
currentPage: {x: number, y: number, pageX: number, pageY: number};
pages: Array<Array<PageInfo>>;

Wheel Picker Feature

Wheel-style picker component for selecting items from a list with 3D rotation effects and momentum scrolling.

interface WheelOptions {
  selectedIndex?: number;
  rotate?: number;
  adjustTime?: number;
  wheelWrapperClass?: string;
  wheelItemClass?: string;
}

// Instance properties when wheel enabled
selectedIndex: number;
items: HTMLElement[];

Pull-to-Refresh Features

Pull-down refresh and pull-up load more functionality with customizable thresholds and callbacks.

interface PullDownRefreshOptions {
  threshold?: number;
  stop?: number;
}

interface PullUpLoadOptions {
  threshold?: number;
}

// Methods added when enabled
finishPullDown(): void;
finishPullUp(): void;

// Events: 'pullingDown', 'pullingUp'

Additional Features

Additional specialized features for enhanced scrolling experiences:

  • Scrollbar: Visual scroll indicators with fade effects and interactive scrolling
  • Mouse Wheel: Desktop mouse wheel support with configurable speed and easing
  • Zoom: Pinch-to-zoom functionality with scale limits and smooth transitions
  • Infinite Scroll: Virtual scrolling for large datasets with tombstone rendering

Features & Plugins

Configuration

Better Scroll provides extensive configuration options organized into logical groups:

  • Movement & Direction: Control scroll axes, free scroll, and direction locking
  • Momentum & Animation: Configure momentum physics, bounce effects, and easing
  • Interaction: Handle touch/mouse events, clicks, and gesture recognition
  • Performance: Hardware acceleration, transition preferences, and DOM observation
  • Features: Enable and configure snap, wheel, scrollbar, pull actions, zoom, etc.

The library includes smart defaults and automatic feature detection for optimal performance across devices.

Types

// Static properties
static Version: string;

// Instance properties
x: number;                    // Current horizontal position
y: number;                    // Current vertical position  
enabled: boolean;             // Whether scrolling is enabled
isInTransition: boolean;      // Whether in CSS transition
hasHorizontalScroll: boolean; // Whether horizontal scrolling possible
hasVerticalScroll: boolean;   // Whether vertical scrolling possible

// Boundary properties
minScrollX: number;           // Minimum horizontal scroll position
maxScrollX: number;           // Maximum horizontal scroll position
minScrollY: number;           // Minimum vertical scroll position
maxScrollY: number;           // Maximum vertical scroll position

// Element references
wrapper: HTMLElement;         // Container element
scroller: HTMLElement;        // Scrolling content element