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, endValues, options);
</script>

What Can Kinex Animate?

Kinex can 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%"). How to animate complex CSS functions like translate(x, y) or rotate() read below.
  3. Smooth Page Scroll: Animates the page scroll position for smoother scrolling effects.

How to Animate?

1. kinex.to(target, endValues, 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.
endValues
An object defining the end values for the properties to animate.
options
Settings including duration (defaults to 1000 ms), easing, delay, and callbacks (on_start, on_update, on_complete).

Minimal Examples

Box Style Animation
const box = document.querySelector('#box');

kinex.to(box.style, { borderRadius: '20px' });
Generic Object Animation
const obj = { value: 0 };

kinex.to(obj, { value: 100 });
Window Scroll Animation
kinex.to(window, { scrollY: 800 },
    { 
        duration: 1000,
        easing: [0.25, 0, 0, 1]
    });

Full Example:

Move an element to a new position and change opacity over 1 second. Animates with 500 milliseconds delay and easing:

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

kinex.to(box.style, { borderRadius: '20px', opacity: 1 }, {
    duration: 1000,
    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, startValues, options)

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

Parameters:

target
The object or element you want to animate.
startValues
An object defining the starting values for the properties to animate.
options
Settings including duration (defaults to 1000 ms), easing, delay, and callbacks (on_start, on_update, on_complete).

Example:

Fade in an element from 0 to its current opacity in 500 milliseconds:

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

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

3. .stop()

Stops an animation.

Example:

Starts and then immediately stops the animation:

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

const boxAnimation = kinex.to(box.style, { 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');

// Animate x and y properties from 0 to 100 and 50 over 1 second (default duration)
kinex.to(position, { x: 100, y: 50 }, {
    on_update: ({ x, y }) => {
        // Apply the animated values to the element's transform property
        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. By specifying these points, you can create custom easing effects like ease-in, ease-out, or a combination of both.

To use cubic Bezier easing, provide an array with four numbers [x1, y1, x2, y2] representing the control points. For example, [0.6, 0, 0.4, 1] creates a smooth ease-in-out effect.

You can use the visual Bezier Curve Editor to create control custom points.

Example:

Animate an element with a custom cubic Bezier easing function:

kinex.to(document.querySelector('#box').style, { left: "200px" }, {
    easing: [0.42, 0, 0.58, 1]
});

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. This is great when you want to chain animations or perform some actions in order.

Example:

async function myAnimation() {

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

    // Wait for the first animation to finish
    await kinex.to(box.style, { left: '200px' }, { duration: 1000 });
    console.log('First animation done!');

    // Start another animation after the first one is complete
    await kinex.to(box.style, { opacity: 0.5 }, { duration: 500 });
    console.log('Second animation done!');

}

myAnimation();

In this example, the first animation moves an element to the left over 1 second. After it finishes, a message is logged, and then a second animation starts to change the opacity. This shows how you can run animations one after another using async/await in a simple way.

Cubic Bézier Curve Editor

Interactive Cubic Bézier Curve Editor Drag the blue control points to adjust the cubic bezier curve. The curve represents animation easing over time.
Copy the current bezier coordinates to clipboard

Breaking Changes in v2.0.0

⚠️ API Changes: If you're upgrading from v1.x, please note the following breaking changes:

Old API (v1.x):

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

New API (v2.0.0+):

kinex.to(target, endValues, options)        // duration moved to options
kinex.from(target, startValues, options)    // duration moved to options

Migration Guide:

// Before (v1.x)
kinex.to(element, 1000, { opacity: 1 }, { easing: [0.25, 0, 0, 1] })
kinex.from(element, 500, { opacity: 0 })

// After (v2.0.0+)
kinex.to(element, { opacity: 1 }, { duration: 1000, easing: [0.25, 0, 0, 1] })
kinex.from(element, { opacity: 0 }, { duration: 500 })

// Or use 1000ms default duration
kinex.to(element, { opacity: 1 }, { easing: [0.25, 0, 0, 1] })
kinex.from(element, { opacity: 0 }, { duration: 500 })