Elastic Container Scroller

Build a mobile-optimized scrollable container with elastic boundary behavior that provides a native-feeling scroll experience.

Requirements

Create a scrollable container component that:

1. Implements elastic edge behavior where scrolling beyond content boundaries creates a rubber-band effect that bounces back
2. Allows selective edge control to enable or disable the elastic effect on individual edges (top, bottom, left, right)
3. Provides boundary enforcement to programmatically return the scroll position to valid boundaries when content becomes out of bounds
4. Configures edge resistance to control how much the scroll resists when dragging beyond boundaries

Technical Constraints

• The solution should work in a mobile web browser environment
• Use touch-based gesture interactions
• Content dimensions may be larger than the wrapper dimensions in one or both directions
• The elastic bounce effect should feel natural and responsive

Test Cases

Basic Elastic Bounce { .test }

• When the user scrolls vertically beyond the top edge and releases, the content bounces back to the top boundary position @test

Selective Edge Control { .test }

• When elastic behavior is disabled for the bottom edge but enabled for the top edge, scrolling beyond the top edge bounces back, but scrolling beyond the bottom edge has no elastic effect @test

Programmatic Boundary Reset { .test }

• When content is programmatically positioned beyond valid boundaries (e.g., y position is 100 when max valid position is 0), calling a reset function returns the content to the nearest valid boundary position with animation @test

Custom Resistance { .test }

• When the resistance factor is increased, dragging beyond boundaries requires more force and travels less distance compared to the default resistance @test

Implementation

@generates

API

interface ScrollOptions {
  // Enable/disable scroll on X axis
  scrollX?: boolean;

  // Enable/disable scroll on Y axis
  scrollY?: boolean;

  // Configure elastic bounce behavior
  // Can be true/false for all edges, or object for per-edge control
  bounce?: boolean | {
    top?: boolean;
    bottom?: boolean;
    left?: boolean;
    right?: boolean;
  };

  // Duration of bounce animation in milliseconds
  bounceTime?: number;

  // Resistance factor when scrolling out of bounds (0-1, lower = more resistance)
  outOfBoundaryDampingFactor?: number;
}

interface ScrollInstance {
  // Current scroll position
  x: number;
  y: number;

  // Maximum scroll boundaries
  maxScrollX: number;
  maxScrollY: number;
  minScrollX: number;
  minScrollY: number;

  // Reset scroll position to valid boundaries
  resetPosition(time?: number): boolean;

  // Cleanup
  destroy(): void;
}

export function createScroller(
  wrapper: HTMLElement,
  options?: ScrollOptions
): ScrollInstance;

Dependencies { .dependencies }

better-scroll { .dependency }

Provides mobile-optimized scrolling with elastic boundary behavior.

@satisfied-by