slik

Slik

Animation / tweening library, ideal for use with HTML5 canvas and or React - Demo

About

Slik uses requestAnimationFrame to tween values over time. You can give it a single value, an array, or an object. Internally Slik converts these values to ImmutableJS ones, and returns the tweened values as ImmutableJS objects (unless only a single value is supplied).

Slik uses ImmutableJS so that when used with React you can keep your components pure (preventing updates if values have not changed) as ImmutableJS returns a new reference when updated, allowing quick checks for changes using PureRenderMixin for example.

Installation

Use npm to install slik.

npm install slik --save --save-exact

I'd recommend pinning to a specific version and using --save-exact and --save to add this to your package.json automatically.

Getting started

• Require slik in the file where you'll be animating.

  import Slik from 'slik';
  

• Setup the values you want to animate. These values can be contained in objects, arrays, or simply be single values. If you're animating a lot of values I'd highly recommend using objects as it makes it easier to refer to your values later.

  Note: these can be nested values.

  const initialValues = {
    headRotation: 0,
    leftArm: {
      upper: 0,
      lower: 0
    }
  };
  

• Create an Animation.

• Initial options: You can pass most of your config in here if you like, or add them using the methods with matching names.

  const animation = new Slik.Animation({
    from: initialValues,
    to: nextValues
    // Defaults below
  
    // duration: 500 (milliseconds)
    // delay: 0 (milliseconds)
    // fps: 120 (frames per second) I would not recommend changing the frame rate
    // ease: Slik.Easing.Linear
    // loop: false
  });
  

• Using methods: Note: fluent API returns the same object for each method (except the playing method which returns a boolean). More info below.

  const animation = new Slik.Animation()
    .from(initialValues)
    .to(nextValues)
    .duration(1000)
    .delay(2000)
    .ease(Slik.Easing.EaseInOutSine)
    .loop(true);
  

• Handle changes in values. Bind a callback to the update event & update your component or redraw your canvas.

• Canvas example

  animation.bind('update', function (values) {
    canvas.render(values);
  });
  

• React example

  componentWillMount () {
    animation.bind('update', function (values) {
      this.setState({
        values: values
      });
    });
  }
  

Animation methods

• Set the values to tween from. Default: Immutable.Map().

  animation.from({hello: 0});
  

• Set the values to tween to. Default: Immutable.Map().

  animation.to({hello: 1});
  

• Set the duration of the animation in milliseconds. Default: 500.

  animation.duration(500);
  

• Set a delay in milliseconds before the animation begins. Default: 0.

  animation.delay(1000);
  

• Set the frame rate of the animation (fps). Default: 120. I would not recommend changing this unless you intentionally want a less smooth animation.

  animation.fps(120);
  

• Set the easing function to use for the animation. Default: Slik.Easing.Linear. Note: you can easily create your own easing functions. More info on this below.

  animation.ease(Slik.Easing.Linear);
  

• Set whether the animation should automatically loop. Default: false.

  animation.loop(false);
  

• Invert the values that you are tweening to. E.g. {value: 1} would become {value: -1}

  animation.invert();
  

• Swap the from & to values to play in reverse.

  animation.reverse();
  

• Start the animation. Alias: play

  animation.start();
  

• Stop the animation, allowing you to restart from the beginning. Alias: reset

  animation.stop();
  

• Pause the animation, allowing you to resume from this point.

  animation.pause();
  

• Return whether the animation is currently playing.

  animation.playing();
  

• Return whether the animation is going to loop.

  animation.looping();
  

• Run a callback once before the animation is initially started (start event). Receives the animation's current values. Automatically unbound after triggered or animation stopped.

  animation.first(function () {});
  

• Run a callback once after the animation has completed (end event). Receives the animation's current values. Automatically unbound after triggered or animation stopped.

  animation.then(function () {});
  

• Bind a callback to a specific animation event (or all events). Alias: on More info on events below.

  animation.bind('type', function () {});
  

• Unbind a callback from a specific animation event (or events). Alias: off More info on events below.

  animation.unbind('type', function () {});
  

• Subscribe to an event (like bind), and return an unsubscribe function (unbind).

  var unsubscribe = animation.subscribe('type', function () {});
  
  unsubscribe();
  

• Get the current value / values. Alias: value

  animation.values();
  

Easing functions

There are a few easing functions available on Slik.Easing.

• Linear
• EaseInOutSine
• EaseInSine
• EaseOutSine
• Dip
• Spring

Events

All events are called with the current values. These may be the initial values or next values if the animation has only just begun, or has ended.

• all - called any time another event is triggered
• start - called when an animation is started
• stop - called when an animation is stopped
• pause - called when an animation is paused
• end - called when an animation completes (excluding loops)
• update - called every frame an animation updates
• loop - called every time an animation loops (if looping)

Custom easing functions

You can provide a custom easing function to ease your values. This function is provided with the following values:

• progress - a value from 0 to 1 as to how complete the animation is
• startTime - the time in milliseconds that the animation began (from performance.now)
• now - the current time in milliseconds (from performance.now)
• duration - the duration of the animation in milliseconds
• fromValue - the value to tween from (single values, not objects)
• toValue - the value to tween to (single values, not objects)

This function simply returns a value from 0 to 1 (or a number outside of this range if you are so inclined), that is used as a multiplier for the values in your animation.

For example a linear easing function simply returns the progress of the animation.

function Linear (progress, startTime, now, duration, fromValue, toValue) {
  return progress;
}

Most easing functions can be accomplished simply by returning a variation of the progress value. E.g.

function EaseOutSine (progress) {
  return Math.sin(progress * Math.PI / 2);
}