JavaScript tweens and springs
npm install flux-tween
Example
Create an animation by calling flux.tween()
or a spring by calling flux.spring()
. Animate between values using to
and from
or animate
a matrix using transform.to
and transform.from
. Hook into the update event to make updates every tick.
spring:
flux.spring(document.getElementById('spring-me'))
.transform.to({ x: 50 })
.on('update', flux.applyMatrix)
.start();
tween:
flux.tween({ x: 0 })
.to({ x: 50 })
.duration(500)
.ease(flux.ease.bounce.in)
.on('update', function(obj) {
console.log(obj.x);
})
.start();
Then hook flux
into requestAnimationFrame
:
function tick() {
flux.update();
requestAnimationFrame(tick);
}
requestAnimationFrame(tick);
Animations
.flux.tween || .flux.spring
.from
.to
.transform.from
.transform.to
.repeat
.yoyo
.stop
.start
.pause
.resume
.reverse
.events
Creates a tween or spring.
When creating a tween, the object
passed will be used as the starting value. If nothing is passed, use from
to set the starting value.
When creating a spring, the object
passed is a shortcut to set
.
If an element is passed, flux
can use the element to calculate the starting transform
values.
Sets the starting value for the tween.
#### `.to(obj)` ---Sets the ending value for the tween.
#### `.transform.from(obj)` ---Sets the starting value for a matrix transformation.
If a starting value isn't set and an element was passed, the starting matrix values will be calculated from the element.
Arguments
-
obj
x
y
z
scaleX
scaleY
scaleZ
rotationX
rotationY
rotationZ
-
Additionally, these shorthand methods are accepted.
scale
rotation
rotate
Sets the ending value for a matrix transformation.
Arguments
#### `.repeat(times)` ---How many times to repeat the animation. Defaults to 0
.
Arguments
* `times` - how many times to repeat. Set to `Infinity` to repeat forever.
#### `.yoyo(bool)`
---
Whether to reverse the animation when repeating. Calling .yoyo()
without a value will set it to true
. Defaults to false
.
Arguments
* `bool` - whether to yoyo
#### `.stop()`
---
Stops the animation.
#### `.start()` ---Starts the animation.
#### `.pause()` ---Pauses the animation. Note that the animation must be started in order to pause.
#### `.resume()` ---Resumes the animation if it is paused. Note that the animation must be started in order to resume.
#### `.reverse()` ---Reverses the animation.
## Events ---.on('update', callback)
update Called when the animation updates.
Arguments
callback(obj, animation)
- A function to call when the animation updates.
obj
is the current state of the animation using .to()
and .from()
.
animation
is an animation object containing:
* playing
: bool, whether the animation is playing
* matrix
: matrix, a CSSMatrix if a matrix has been set with .transform.to()
and .transform.from()
* elem
: element if one was passed in the constructor
.on('start', callback)
start Called when the animation starts.
Arguments
* 'callback' - a callback function
.on('stop', callback)
stop Called when the animation stops.
Arguments
* 'callback' - a callback function
.on('complete', callback)
complete Called when the animation completes. This is the finished state for the animation. It is recommended that a new object be created for further animations after this event.
Arguments
* 'callback' - a callback function
Tween specific #### `.duration(ms)` ---
Sets the duration in ms for the tween to run. Defaults to 1000
.
Arguments
* `ms` - Number of milliseconds for the animation to run.
#### `.ease(fn)`
---
The easing function to use for the tween. See flux.easing
. Defaults to linear
.
Arguments
* `fn` - An easing function.
Spring specific #### `.set(obj)`
Sets the spring's tension, friction and velocity.
Arguments
#### `.tension(num)`Sets the spring tension.
Arguments
* `num` - tension
#### `.friction(num)`
Sets the spring friction.
Arguments
* `num` - friction
#### `.velocity(num)`
Sets the spring velocity.
Arguments
* `num` - velocity
Quality of life
If an element is passed in the constructor
, you can apply matrix transformations via: .on('update', flux.applyMatrix)
.
flux.spring(document.getElementById('spring-me'))
.transform.to({ x: 50 })
.on('update', flux.applyMatrix)
.start();
which is the same as:
flux.spring(document.getElementById('spring-me'))
.transform.to({ x: 50 })
.on('update', function(obj, anim) {
anim.elem.style[flux.transform] = anim.matrix.toString();
})
.start();
flux.transform
contains the transformation property to use for styles in the current browser.
var elem = document.getElementById('animate-me');
elem.style[flux.transform] = 'rotateX(90deg)';
All methods on the animation are chainable for easy animation creation.
Plugins
Register functions to flux
to implement custom logic for your animations...
flux.plugin('log', function(opts) {
if (opts && opts.start) {
var inst = this;
inst.on('start', function() {
console.log('starting!');
})
}
});
...then invoke the plugin when you want to use it:
flux.spring(document.getElementById('spring-me'))
.transform.to({ x: 50 })
.on('update', flux.applyMatrix)
.log({ start: true })
.start();
Support
Modern browsers and IE9+
Credit to
License
The MIT License (MIT)
Copyright (c) 2014 Joseph Clay
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.