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

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

   import Slik from 'slik';

2. 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
     }
   };

3. Create an Animation.

4. 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
   });

5. 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);

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

7. Canvas example

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

8. React example

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

Animation methods

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

   animation.from({hello: 0});

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

   animation.to({hello: 1});

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

   animation.duration(500);

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

   animation.delay(1000);

5. 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);

6. 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);

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

   animation.loop(false);

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

   animation.invert();

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

   animation.reverse();

10. Start the animation. Alias: play

    animation.start();

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

    animation.stop();

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

    animation.pause();

13. Return whether the animation is currently playing.

    animation.playing();

14. Return whether the animation is going to loop.

    animation.looping();

15. 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 () {});

16. 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 () {});

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

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

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

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

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

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

20. 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);
}