Kinex Animation Library

Kinex (Kinetic Expressions): The World's smallest and fastest JavaScript animation library, designed to meet 90% of common daily animation needs.

Installation

npm i @nordskill/kinex

Usage

You can use Kinex in your project either via ES Modules or directly in the browser.

Use as ES Module

import kinex from 'kinex';

Include in a Browser Environment

<script src="path/to/kinex.min.js"></script>
<script>
    // kinex.to(target, duration, properties, options);
</script>

What Can Kinex Animate?

  1. JavaScript Object Properties: Any numeric property of an object.
  2. HTML Element Styles: Animates styles like width, height, opacity, or any other CSS property that uses simple numeric values with units (e.g., "20px", "50%").
  3. Smooth Page Scroll: Animates the page scroll position for smoother scrolling effects.

How to Animate?

1. kinex.to(target, duration, properties, options)

Animates the specified properties of the target to new values over a given duration.

Parameters:

  • target: The object or element you want to animate.
  • duration: The duration of the animation in milliseconds.
  • properties: An object defining the end values for the properties to animate.
  • options (optional): Additional settings like easing, delay, and callbacks (on_start, on_update, on_complete).

Minimal Example:

const box = document.querySelector('#box');
Kinex.to(box, 1000, { borderRadius: '20px' });

Full Example:

const box = document.querySelector('#box');

Kinex.to(box, 1000, { borderRadius: '20px', opacity: 1 }, {
    delay: 500,
    easing: [0.5, 0, 0, 1],
    on_start: () => console.log('box animation starts'),
    on_update: (values) => console.log(`Current opacity is ${values.opacity}.`),
    on_complete: () => console.log('box animation is complete')
});

2. kinex.from(target, duration, properties, options)

Animates the properties of the target from the specified values to their current values.

Parameters:

Same as kinex.to, but properties define the starting values instead.

Example:

const circle = document.querySelector('#circle');

kinex.from(circle, 500, { opacity: 0 });

3. .stop()

Stops an animation.

Example:

const boxAnimation = kinex.to(box, 1000, { opacity: 0 });
boxAnimation.stop();

4. kinex.stop_all()

Stops all running animations immediately.

Example:

kinex.stop_all();

Animating Object Properties or Complex CSS Styles

Since complex CSS properties like translate(x, y) cannot be animated directly, you can animate an object and apply those values manually in an on_update callback:

Example:

const position = { x: 0, y: 0 };
const element = document.querySelector('#movingElement');

kinex.to(position, 1000, { x: 100, y: 50 }, {
    on_update: ({ x, y }) => {
        element.style.transform = `translate(${x}px, ${y}px)`;
    }
});

Cubic Bezier Easing in Kinex

Kinex supports custom easing functions using cubic Bezier curves, which allow for more complex and smooth animations. A cubic Bezier curve is defined by four control points that shape the curve's acceleration and deceleration over time.

Example:

Kinex.to(document.querySelector('#box'), 1000, { left: "200px" }, {
    easing: [0.42, 0, 0.58, 1] // Custom cubic Bezier easing
});

Using Promises with Kinex

Kinex animations return a promise, which means you can easily run some code after the animation finishes. You can use async/await to make this even simpler, allowing you to wait for the animation to complete before doing something else.

Example:

async function myAnimation() {
    const box = document.querySelector('#box');

    await kinex.to(box, 1000, { left: '200px' });
    console.log('First animation done!');

    await kinex.to(box, 500, { opacity: 0.5 });
    console.log('Second animation done!');
}

myAnimation();