spring-easing

yarn add spring-easing
Copy

or

pnpm install spring-easing
Copy

NEW CSS Spring Easing & support for the linear() easing function

CSSSpringEasing

Generates a string that represents a set of values used with the linear-easing function to replicate spring animations, you can check out the linear-easing playground here https://linear-easing-generator.netlify.app/ Or check out a demo on Codepen https://codepen.io/okikio/pen/vYVaEXM

CSS Spring Easing has 4 properties they are easing (all spring frame functions are supported), numPoints (the size of the Array the frmae function should create), decimal (the number of decimal places of the values within said Array) and quality (how detailed/smooth the spring easing should be)..

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

CSSSpringEasing is meant to be used with the linear-easing() function to replicate spring animations. It is based on the work done by Jake Archibald in his Linear Easing Generator.

Note: This feature will only work on versions of browsers from ~a month ago (Chrome & Edge 113, and Firefox 112) except for Safari which doesn't support it yet.

import { CSSSpringEasing } from "spring-easing";

let [easing, duration] = CSSSpringEasing({
  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 {@link GenerateSpringFrames}
  decimal: 5,

  // How detailed/smooth the spring easing should be
  // 0 means not smooth at all (shorter easing string)
  // 1 means as smooth as possible (this means the resulting easing will be a longer string)
  quality: 0.85,
});

document.querySelector("div").animate(
  {
    translate: ["0px", "250px"],
    rotate: ["0turn", "1turn", "0turn", "0.5turn"],
  },
  {
    easing: `linear(${easing})`,

    // The optimal duration for this specific spring
    duration,
  }
);
Copy

Note: You can also use custom easings with CSSSpringEasing e.g.

import {
  CSSSpringEasing,
  limit,
  registerEasingFunctions,
} from "spring-easing";

registerEasingFunctions({
  bounce: (t) => {
    let pow2: number,
      b = 4;
    while (t < ((pow2 = Math.pow(2, --b)) - 1) / 11) {}
    return (
      1 / Math.pow(4, 3 - b) - 7.5625 * Math.pow((pow2 * 3 - 2) / 22 - t, 2)
    );
  },
  elastic: (t, params: number[] = []) => {
    let [amplitude = 1, period = 0.5] = params;
    const a = limit(amplitude, 1, 10);
    const p = limit(period, 0.1, 2);
    if (t === 0 || t === 1) return t;
    return (
      -a *
      Math.pow(2, 10 * (t - 1)) *
      Math.sin(
        ((t - 1 - (p / (Math.PI * 2)) * Math.asin(1 / a)) * (Math.PI * 2)) / p
      )
    );
  },
});

CSSSpringEasing("bounce"); // ["0, 0.013, 0.015, 0.006 8.1%, 0.046 13.5%, 0.06, 0.062, 0.054, 0.034, 0.003 27%, 0.122, 0.206 37.8%, 0.232, 0.246, 0.25, 0.242, 0.224, 0.194, 0.153 56.8%, 0.039 62.2%, 0.066 64.9%, 0.448 73%, 0.646, 0.801 83.8%, 0.862 86.5%, 0.95 91.9%, 0.978, 0.994, 1", ...]
CSSSpringEasing("elastic(1, 0.5)"); // ["0, -0.005 32.4%, 0.006 40.5%, 0.034 51.4%, 0.033 56.8%, 0.022, 0.003, -0.026 64.9%, -0.185 75.7%, -0.204, -0.195, -0.146, -0.05, 0.1 89.2%, 1", ...]
Copy

getOptimizedPoints

This function generates an optimized set of points to be used with the linear-easing() function using the Ramer-Douglas-Peucker algorithm and rounds the x and y values of the resulting points.

import { getOptimizedPoints } from "spring-easing";

const points = [
  [0, 0],
  [0.1, 0.2],
  [0.5, 1],
  [0.9, 0.2],
  [1, 0],
];
const round = 2;
const simplify = 0.1;

console.log(getOptimizedPoints(points, simplify, round)); //= [[0, 0], [0.5, 1], [1, 0]]
Copy

getLinearSyntax

This function converts a given set of points into an array of strings in a this format ["value percent%", ...] e.g. ["0", "0.25 13.8%", "0.6 45.6%", "0.1", "0.4 60%", ...]. It's used to generate the syntax for the linear-easing function.

import { getLinearSyntax } from "spring-easing";

const points = [
  [0, 0],
  [0.1, 0.2],
  [0.5, 1],
  [0.9, 0.2],
  [1, 0],
];
const round = 2;

console.log(getLinearSyntax(points, round)); //= [ '0', '0.2 10%', '1', '0.2 90%', '0' ]
Copy

RE-INSTATED Added batch version of SpringEasing and the Interpolation functions which use a new syntax.

The other version of spring-easing interpolation functions follow this syntax (t, values, decimal) => string | number | any, batch interpolation function use this new syntax (arr_t, 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, but for those high-perf. applications this new batch synatax should prove useful. e.g.

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

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

BatchSpringEasing([0, 250], `spring`, batchInterpolateNumber);
Copy

RE-INSTATED There is a new toAnimationFrames function that converts interpolation functions written in this style (t, values, decimal) => { ... } to work in BatchSpringEasing. e.g.

import {
  BatchSpringEasing,
  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`;
}

BatchSpringEasing([0, 250], "spring", toAnimationFrames(interpolatePixels));
Copy

NEW Optimized perf. of spring generation w/ help from @jakearchibald

NEW mass, stiffness, damping, and velocity now have a smaller minimum limit of 0.0001 instead of 0.1

REVERT The new interpolation syntax has been reverted and removed; instantNumber, etc... functions have been renamed to interpolateNumber, etc...

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

import {
  interpolateNumber,
  interpolateString,
  interpolateSequence,
  interpolateComplex,
} from "spring-easing";
Copy

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.

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";
Copy

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);
Copy

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));
Copy

NEW Easily register new easing functions. e.g.

import { SpringEasing, registerEasingFunction } from "spring-easing";

registerEasingFunction("linear", (t) => t);
registerEasingFunctions({
  quad: (t) => Math.pow(t, 2),
  cubic: (t) => Math.pow(t, 3),
});

SpringEasing([0, 250], "linear");

SpringEasing([0, 250], "quad");
Copy

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], ...)
Copy

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, toFixed, scale, limit } from "spring-easing";
// ...
export function interpolateColor(t: number, values: string[], decimal = 3) {
  const color = transpose(...values.map((v) => rgba(v))).map(
    (colors: number[], i) => {
      const result = interpolateNumber(t, colors);
      return i < 3 ? Math.round(result) : toFixed(result, decimal);
    }
  );

  return `rgba(${color.join()})`;
}

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

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