spring-easing - v2.1.0

spring-easing

Open Bundle

NPM | GitHub | Docs | Licence

Quick and easy spring animations. Works with other animation libraries (gsap, animejs, @okikio/animate, motion one, framer motion, etc...) or the Web Animation API (WAAPI), you can learn more in the Usage section.

spring-easing works by generating arrays of frame's which when placed in linear order creates a smooth spring like animation.

A frame represent a single frame of an animation

Note: the spring-easing package also supports 4 extra variants of spring, namely spring-in, spring-out, spring-out-in, and spring-in-out, you can use these easing to create some really unique spring like animations.

You can create animation's like this with spring-easing,

A demo of the various spring-easings available

Check out the spring easing variants on Codepen.

Attention: This entire library is a lightweight version of the CustomEasing implemented in @okikio/animate, which supports only string and number interpolation. If you'd like the complete CustomEasing with color interpolation, complex value interpolation, and more, go through the source code as a Github Gist, which is licensed under the MIT license.

Installation

npm install spring-easing
Others
yarn add spring-easing

or

pnpm install spring-easing

Usage

import { SpringEasing } from "spring-easing";
// or
import SpringEasing from "spring-easing";

You can also use it directly through a script tag:

<script src="https://unpkg.com/spring-easing" type="module"></script>
<script type="module">
// You can then use it like this
const { SpringEasing } = window.SpringEasing;
</script>

You can also use it via a CDN, e.g.

import SpringEasing from "https://cdn.skypack.dev/spring-easing";
// or
import SpringEasing from "https://cdn.jsdelivr.net/npm/spring-easing";
// or any number of other CDN's

Use with Animation Libraries

Note: I cannot guarantee that every animation library works with spring-easing, for example, if an animation library doesn't support array values as keyframes, it won't work well with spring-easing.

The libraries that have been tested are:

Animation Library Support Demo
GSAP ✅ Yes - Wrap Method Codepen
animejs ✅ Yes - Array Keyframes Codepen
Framer Motion ✅ Yes - Array Keyframes Codepen
Motion One ✅ Yes - Array Keyframes Codepen
@okikio/animate ✅ Yes - Array Keyframes Codepen
Web Animation API (WAAPI) ✅ Yes - Array Keyframes Codepen

e.g.

import anime from "animejs";
import { SpringEasing, SpringOutFrame } from "spring-easing";

// Note: this is the return value of `SpringEasing` and `GenerateSpringFrames`
let [translateX, duration] = SpringEasing([0, 250], {
easing: "spring-out-in(1, 100, 10, 0)",
// You can change the size of Array for the SpringEasing function to generate
numPoints: 200,
// The number of decimal places to round, final values in the generated Array
// This option doesn't exist on `GenerateSpringFrames`
decimal: 5,
});

anime({
targets: "div",

// Using spring easing animate from [0 to 250] using `spring-out-in`
translateX,

// You can interpolate between strings
// You can set the easing without an easing options object
// You can interpolate between more than 2 values
// Remember the `0` index of `SpringEasing` is an array of spring animation keyframes
rotate: SpringEasing(
["0turn", 1, 0, 0.5],
[SpringOutFrame, 1, 100, 10, 0]
)[0],

// TIP... Use linear easing for the proper springy effect
easing: "linear",

// The optimal duration for this specific spring configuration, e.g. mass, velocity, damping, etc...
duration,
});

Note: make sure to read the comments above, as they are valuable resources for understanding what is happening.

Check out this demo on Codepen


Showcase

A couple sites/projects that use spring-easing:

  • Your site/project here...

API

What's New...

NEW (deprecated) interpolateUsingIndex is now an alias of interpolateSequence, it still keeps the same functionality. The recommendation is to use interpolateSequence instead of interpolateUsingIndex, but you can still keep using interpolateUsingIndex, but beware it can be removed in future versions.

NEW Re-introduced instantaneous interpolation functions. e.g.

import { instantNumber, instantString, instantSequence, instanceComplex } from "spring-easing";

These functions represent the interpolated value at a specific instance in time, where time is represented by t with a range of 0 to 1. You can use these functions as building blocks to create your own custom interpolation functions.

BREAKING CHANGE Interpolation functions use a new syntax.

In older versions of spring-easing interpolation functions used to follow a syntax called the instantaneous interpolation function (t, values, decimal) => string | number | any, the new syntax is called interpolation function (frames, values, decimal) => string[] | number[] | any[].

The key difference between both syntaxes are the parameters each function takes and the return value of each function.

The older syntax returned instantaneous frame values at a specific t-value, but the new syntax returns all the frames that make the entire animation, allowing for performance optimizations that couldn't be done before.

For the most part this shouldn't leave too much of an effect as all the built-in interpolation functions have been updated to use the new synatax. e.g.

function interpolateNumber(frames: number[], values: number[], decimal = 3) {
// nth index
const n = values.length - 1;

return frames.map(t => {
// The current index given t
const i = limit(Math.floor(t * n), 0, n - 1);

const start = values[i];
const end = values[i + 1];
const progress = (t - i / n) * n;

return toFixed(scale(progress, start, end), decimal);
});
}

SpringEasing([0, 250], `spring`, interpolateNumber)

NEW There is a new toAnimationFrames function that be used on instantaneous interpolation functions, to transform them into complete animation interpolation functions. e.g.

import { SpringEasing, toAnimationFrames, toFixed, scale, limit } from "spring-easing";

function interpolateNumber(t: number, values: number[], decimal = 3) {
// nth index
const n = values.length - 1;

// The current index given t
const i = limit(Math.floor(t * n), 0, n - 1);

const start = values[i];
const end = values[i + 1];
const progress = (t - i / n) * n;

return toFixed(scale(progress, start, end), decimal);
}

function interpolatePixels(t: number, values: number[], decimal = 3) {
const result = interpolateNumber(t, values, decimal);
return `${result}px`;
}

SpringEasing(
[0, 250],
'spring',
toAnimationFrames(interpolatePixels)
);

NEW Easily register new easing functions. e.g.

import { SpringEasing, register, toAnimationFrames, toFixed, scale, limit } from "spring-easing";

function interpolateNumber(t: number, values: number[], decimal = 3) {
// nth index
const n = values.length - 1;

// The current index given t
const i = limit(Math.floor(t * n), 0, n - 1);

const start = values[i];
const end = values[i + 1];
const progress = (t - i / n) * n;

return toFixed(scale(progress, start, end), decimal);
}

function interpolatePixels(t: number, values: number[], decimal = 3) {
const result = interpolateNumber(t, values, decimal);
return `${result}px`;
}

SpringEasing(
[0, 250],
'spring',
toAnimationFrames(interpolatePixels)
);

NEW SpringEasing now support interpolating between strings. It treats the units of the first value as the units for the rest of the values to interpolate between. e.g.

SpringEasing(["0turn", "1px", "18rem", "125deg", 25], ...)

Important All the values above get transformed to ["0turn", "1turn", "18turn", "125turn", "25turn"], before being interpolated.

NEW interpolateStrings, interpolateUsingIndex, and interpolateComplex, are now built-in, they allow for supporting string keyframes.

NEW Custom interpolation functions are now supported. e.g.

import { interpolateNumber } from "spring-easing";
// ...
export function interpolateColor(frames, values, decimal = 3) {
const rgbColors = transpose(...values.map((v) => rgba(v)))
.filter((colors) => Array.isArray(colors));

return transpose(
...rgbColors.map((colors, i) => {
return interpolateNumber(frames, colors as number[])
.map(result => i < 3 ? Math.round(result) : toFixed(result, decimal));
})
).map(color => `rgba(${color.join()})`);
}

SpringEasing(["red", "green", "#4f4"], "spring", interpolateColor);

Important The logic for color interpolation is defined in this tests/utils/interpolate-color.ts.

The API of spring-easing is pretty straight forward, the SpringEasing function generates an array of values using a frame functions, which in turn creates the effect of spring easing.

To use this properly make sure to set the easing animation option to "linear". Check out a demo of SpringEasing at https://codepen.io/okikio/pen/MWEdzNg

SpringEasing has 3 properties they are easing (all the easings from EasingFunctions are supported on top of frame functions like SpringFrame, SpringFrameOut, etc..), numPoints (the size of the Array the frame function should create), and decimal (the number of decimal places of the values within said Array).

Properties Default Value
easing spring(1, 100, 10, 0)
numPoints 50
decimal 3

By default, Spring Easing support easings in the form,

constant accelerate decelerate accelerate-decelerate decelerate-accelerate
spring / spring-in spring-out spring-in-out spring-out-in

All Spring easing's can be configured using theses parameters,

spring-*(mass, stiffness, damping, velocity)

Each parameter comes with these defaults

Parameter Default Value
mass 1
stiffness 100
damping 10
velocity 0

To understand what each of the parameters of SpringEasing mean and how they work I suggest looking through the SpringEasing API Documentation

Note: the return value of the SpringEasing function is actually [Array of keyframes , duration], in that order.

For a full understanding of what is happening in the library out the API site for detailed API documentation.

Browser Support

Chrome Edge Firefox Safari IE
4+ 12+ 4+ 4+ 10+

Native support for spring-easing is great as it doesn't use any browser specific or nodejs specific API's, you should be good to use spring-easing in any environment.

Contributing

I encourage you to use pnpm to contribute to this repo, but you can also use yarn or npm if you prefer.

Install all necessary packages

npm install

Then run tests

npm test

Build project

npm run build

Preview API Docs

npm run typedoc && npm run preview

Note: this project uses Conventional Commits standard for commits, so, please format your commits using the rules it sets out.

Licence

See the LICENSE file for license rights and limitations (MIT).

Generated using TypeDoc