spring-input

A utility to provide a springy mouse and touch input, similar to bouncy scroll panels in iOS. This can be used in a variety of applications, such as scrolling, rotating a 3D camera, flicking a 2D card, etc.

Demo:

http://mattdesl.github.io/spring-input/

Adapted from touch-scroll-physics, which is more application-specific than this module.

Install

npm install spring-input --save

Example

See test.js for a full example.

var createSpring = require('spring-input')
 
// e.g. a slider along the x-axis
var spring = createSpring({
  min: 0,        // min bound
  max: 1,        // max bound
  edge: 0.1,     // gutter size
  value: 0.5,    // initial value
  damping: 0.25, // flick friction
  spring: 0.15   // "bounce back" friction
})
 
function onDragStart (x, y) {
  spring.start(x)
}
 
function onDragMove (x, y) {
  spring.move(x)
}
 
function onDragEnd (x, y) {
  spring.end(x)
}
 
function onRequestAnimationFrame () {
  spring.update()
}

This is a low-level module, intended to be used with your own input handling and update loop. This can be easily combined with the following modules:

• touches - unified mouse / touch input and drag events
• mouse-wheel - cross-browser mouse wheel events
• raf-loop - a simple requestAnimationFrame loop

Usage

spring = createSpring([opt])

Creates a new sprint input with the optional settings:

• value - the initial value, default 0
• min - the minimum bound, default 0 (can be -Infinity)
• max - the maximum bound, default 1 (can be Infinity)
• edge - the relative edge gutter size, default 0 (i.e. no "bounce back")
• damping - adjusts the friction when flicking; defualt 0.3
• spring - adjusts the friction when bouncing back; default 0.2
• maxVelocity - the maximum velocity in a flick, default 0.05

All values can be changed during runtime, eg:

spring.max = newScrollHeight

spring.start(value)

Called to trigger a "start" event with the specified value, such as the initial X mouse position.

spring.move(value)

Called to trigger a "move" event with the specified value, such as a new mouse X position.

spring.end()

Stops user input, allowing the value to be integrated and slide into place.

spring.update()

Integrates the spring. Should be called once per animation loop.

spring.value

The currently integrated value.

spring.velocity

The current velocity.

See Also

• touch-scroll-physics very similar, but more application-specific

License

MIT, see LICENSE.md for details.