troika-animation v0.49.0

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:

1. Create a Tween describing the start and end values, how the value should change over time, and a callback to invoke on each frame
2. Create a Runner
3. 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 Tweens. 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.