spring-easing
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 ofspring
, namelyspring-in
,spring-out
,spring-out-in
, andspring-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
,
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 completeCustomEasing
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 withspring-easing
.
The libraries that have been tested are:
Animation Library | Support | Demo |
---|---|---|
GSAP |
|
Codepen |
animejs |
|
Codepen |
Framer Motion |
|
Codepen |
Motion One |
|
Codepen |
@okikio/animate |
|
Codepen |
Web Animation API (WAAPI) |
|
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
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
, andinterpolateComplex
, 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 const interpolateColor = (t, values, decimal) => { return transpose(...values.map((v) => toRGBAArr(v))).map( (colors, i) => { let result = interpolateNumber(t, colors); return i < 3 ? Math.round(result) : toFixed(result, decimal); } ); }; SpringEasing(["red", "green", "#4f4"], "spring", interpolateColor)Important The logic for color interpolation is defined in this Github Gist.
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).