bouncr

Framework-agnostic rubber-band gesture physics for PWAs and web apps. Built with TypeScript, zero runtime dependencies.

Install

npm install bouncr

Quick Start

import { createRubberBand } from 'bouncr';

const el = document.getElementById('pull-surface') as HTMLElement;

const rubberBand = createRubberBand(el, {
  thresholds: { down: 110 },
  effects: { haptics: true },
  callbacks: {
    onThresholdEnter: ({ direction, progress }) => {
      console.log('threshold reached', direction, progress);
    },
    onAction: () => {
      console.log('trigger refresh');
    }
  }
});

// later
rubberBand.destroy();

Features

• Logarithmic resistance (R * ln(1 + d / R))
• Directional gesture support (down, up, left, right)
• Threshold enter/exit hooks
• Optional haptic notch (navigator.vibrate(10))
• Interpolated progress and opacity values
• Snap-back animation presets

Scripts

• npm run dev watch build with tsup
• npm run build production build
• npm run test run unit tests
• npm run lint lint TypeScript files
• npm run typecheck strict type checking

API

createRubberBand(element, config?)

Returns a controller:

• destroy() remove listeners and stop updates
• reset() clear transform and internal state
• setConfig(partial) update runtime config
• getState() snapshot of current gesture state

See src/types.ts for full type definitions.