troika-animation
v0.52.0
Published
Troika Animation Utilities
Downloads
1,623
Readme
Troika Animation
This package provides a small library for "tweening" values over time, heavily optimized for performance. It is used by the Troika framework behind the scenes for its declarative transition
and animation
features, but can also be used as a standalone library.
Installation
If you're using the Troika framework, you don't need to install this directly. If you want to use it standalone, you can get it from NPM:
npm install troika-animation
Usage
To animate a value, you basically need to:
- Create a
Tween
describing the start and end values, how the value should change over time, and a callback to invoke on each frame - Create a
Runner
- Start the tween in the runner
Tween
See the JSDoc comments in Tween.js for more details about each parameter.
import { Tween } from 'troika-animation'
function onTweenFrame(tweenedValue) {
// ...do something with the tweenedValue
}
const tween = new Tween(
onTweenFrame, // callback
-100, // fromValue
100, // toValue
5000, // duration in ms
0, // delay
'easeOutExpo', // easing
1, // iterations
'forward', // direction
'number' // interpolation
)
MultiTween
This is a specialized Tween
that, instead of managing a value, manages a list of other Tween
s. It essentially creates a sub-timeline, whose playback is controlled as a whole. For example you can apply an easing
to the entire set of tweens as a whole, stretch out their duration, repeat them, etc.
import { MultiTween, Tween } from 'troika-animation'
const tween1 = new Tween(/*...*/)
const tween2 = new Tween(/*...*/)
const multiTween = new MultiTween(
[tween1, tween2], // list of tweens
5000, // duration
0, // delay
'easeInOutExpo', // easing
10, // iterations
'alternate' // direction
)
SpringTween
See the JSDoc comments in SpringTween.js for more details about each parameter.
This is a lot like Tween
but instead of having a fixed duration, its value is transitioned using a simple spring physics simulation.
import { SpringTween } from 'troika-animation'
const tween = new Tween(
onTweenFrame, // callback
-100, // fromValue
100, // toValue
{ // spring simulation config, or the name of a preset
mass: 1, // object mass
tension: 170, // spring tension force
friction: 26 // friction force
},
0 // delay
)
The meanings of the spring configuration parameters match those from react-spring. The named presets also match those defined by react-spring.
Runner
Also see the JSDoc comments in Runner.js
import { Tween, Runner } from 'troika-animation'
const tween = new Tween(/*...*/)
const runner = new Runner()
runner.start(tween)
Easings
When constructing a Tween, the easing
parameter controls the rate of change over time. You can either specify a string, referring to the name of one of the built-in easing functions, or you can provide a custom easing function.
Built-in named easings
The built-in named easings can be found in Easings.js. These may be familiar, as they mostly match the ones provided by the popular jQuery Easing Plugin and easings.net.
There is also an online demo of troika-animation easings that shows the curve for each.
Custom easing functions
An easing function takes a single parameter t
, which refers to the fraction of time passed in the tween's duration from 0 to 1. It must return a number specifying the progress between the start and end values at t
; 0 corresponds to the start value and 1 corresponds to the end value. Most easings stay in the range from 0 to 1 but some may exceed it.
Interpolation
The tween interpolation
parameter controls how the fractional value returned from the easing
is applied to the start and end values to calculate the in-between value. In most cases you're probably tweening two numbers, which is handled as the default interpolation. But if you have a different type of value, you may need to change the interpolator.
Two built-in interpolation types are provided, which can be referred to by their string names (see Interpolators.js)
"number"
- simple linear interpolation between two numeric values (the default)."color"
- interprets the start/end values as RGB colors, and interpolates each color channel independently. The start/end values can be 24-bit integers or any CSS color string value, and the interpolated values will always be returned as 24-bit integers (8 bits red, 8 bits green, 8 bits blue.)
If you need a different interpolation, you can provide a custom function. Your function will take three parameters: the start value, the end value, and the progress between them (the output of the easing function) in the range from 0
to 1
. It must return an in-between value of the appropriate type.