impulsion

Impulsion.js

Fork of the excellent impetus.js by Chris Bateman.

Adds new features such as:

• Exposes previousX and previousY to our lifecycle events.
• Adds more lifecycle events:
  • onStart: Called when starting to drag the element.
  • onStartDecelerating: Called when the deceleration begun.
  • onEndDecelerating: called when the deceleration has ended.

As well other bugfixes and minor features.

Add momentum to anything. It's like iScroll, except not for scrolling. Supports mouse and touch events.

Check out the demos on the home page.

Impulsion will probably never support anything other than simple momentum. If you need scrolling or touch carousels or anything like that, this probably isn't the tool you're looking for.

Installation

yarn add impulsion
# or npm install impulsion

Usage

import Impulsion from 'impulsion';
// const Impulsion = require('impulsion');

let myImpulsion = new Impulsion({
    source: myNode,
    onUpdate(x, y, previousX, previousY) {
        // whatever you want to do with the values
    }
});

You give it an area to listen to for touch or mouse events, and it gives you the x and y values with some momentum.

Impulsion will register itself as an AMD module if it's available.

Constructor Options

	Type	Default	Description
source	HTMLElement|String	window	Element reference or query string for the target on which to listen for movement.
onStart	function(x, y, px, py)	-	This function will be called when starting to drag the element. px and py are the previous x and y values.
onUpdate (required)	function(x, y, px, py)	-	This function will be called with the updated x and y values. px and py are the previous x and y values.
onStartDecelerating	function(x, y, px, py)	-	This function will be called when the deceleration begun (and drag has ended). px and py are the previous x and y values.
onEndDecelerating	function(x, y, px, py)	-	This function will be called when the deceleration has ended. px and py are the previous x and y values.
multiplier	Number	1	The relationship between the input and output values.
friction	Number	0.92	Rate at which values slow down after you let go.
initialValues	[Number, Number]	[0, 0]	Array of initial x and y values.
boundX	[Number, Number]	-	Array of low and high values. x-values will remain within these bounds.
boundY	[Number, Number]	-	Array of low and high values. y-values will remain within these bounds.
bounce	Boolean	true	Whether to stretch and rebound values when pulled outside the bounds.
window	HTMLElement	window	Specify the root window element, only really needed when trying to applied Impulsion to child iframes.
addIosTouchmoveFix	Boolean	true	iOS sometimes fails to preventDefault when scrolling on the body. Per this comment, one fix is to add an empty touchmove listener to the main window. This library adds this by default, but if you want to override this hacky listener, it can be disabled by setting this option to false. Other information: Can't prevent "touchmove" from scrolling window on iOS touchstart preventDefault() does not prevent click event.

Methods

	Description
.pause()	Disable movement processing.
.resume()	Re-enable movement processing.
.forceUpdate()	Call the onUpdate function manually. Can be used to update the scene after setValues() has been run.
.setMultiplier( <number> )	Adjust the multiplier in flight.
.setValues( <number> , <number> , <number|null> , <number|null>)	Adjust the current x, y, previousX and previousY output values. previousX and previousY can be null.
.setBoundX( <number[2]> )	Adjust the X bound
.setBoundY( <number[2]> )	Adjust the Y bound
.destroy()	This will remove the previous event listeners. Returns null so you can use it to destroy your variable if you wish, i.e. instance = instance.destroy()

Browser Support

Chrome, Firefox, Safari, Opera, IE 9+, iOS, Android. Support for IE 8 can be achieved by adding a polyfill for addEventListener.