`bash
yarn add postcss-spring-easing
`

or

`bash
pnpm install postcss-spring-easing
`

`bash
yarn add postcss
`

or

`bash
pnpm install postcss
`

Check your project for an existing PostCSS config: postcss.config.js in the project root,"postcss" section in the package.json or postcss in your bundle config.

Add the plugin to plugins list:
`diff
module.exports = {
plugins: [
+ require('postcss-spring-easing').default,
require('autoprefixer')
]
}
`

Or

`ts
// dependencies
var fs = require("fs")
var postcss = require("postcss")
var { springEasingPlugin } = require("postcss-spring-easing")

// css to be processed
var css = fs.readFileSync("input.css", "utf8")

// process css
var output = postcss()
.use(springEasingPlugin())
.process(css)
.css
`
Checkout tests for more examples.

Usage

To create a spring animation, you just need to write your CSS transitions as usual, but replace the timing function with one of the following:

* spring
* spring-in
* spring-out
* spring-in-out
* spring-out-in

Each of these represents a different type of spring effect.

For example:

`css
.box {
transition: transform 1s spring-out;
}
`

This will give a spring effect to the transform transition of the .box element.

The spring-out function here means that the animation will start slowly and end quickly, like a spring being released. Similarly, spring-in would start quickly and end slowly, and spring-in-out would start and end slowly with a quick middle, resembling the movement of a bouncing spring.

Now your animations are ready to bounce!

Have questions? Or just wanna talk--leave a message on GitHub Discussions

Showcase

A couple sites/projects that use postcss-spring-easing:

- Your site/project here...

Options

postcss-spring-easing has 4 options they are
* easing (all the easings from EasingFunctions are supported),
* easings (list of extra custom easings to support),
* decimal (the number of decimal places of the resulting values), and
* quality (how detailed/smooth the spring easing should be)

| Properties | Default Value |
| ----------- | ----------------------- |
| easing | spring(1, 100, 10, 0) |
| easings | {} |
| decimal | 3 |
| quality | 0.85 |

$3

By default, spring easings are supported 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

For a full understanding of what is happening in the SpringEasing library, pleace check out its API site for detailed API documentation.


`css
a {
transition: all var(--spring-duration) spring(1, 100, 10, 0);
}
`

$3

Allow to set custom easings:

`js
require('postcss-spring-easing').default({
easings: {
bounceOut: t => {
let pow2, 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);
},
}
})
`

The plugin will convert custom easing name between camelCase and snake-case.
So the example above would work for bounce-out and bounceOut easings.

Browser Support

| Chrome | Edge | Firefox | Safari | IE |
| ------ | ---- | ------- | ------ | --- |
| 113+ | 113+ | 112+ | - | - |

postcss-spring-easing is meant for browsers which have support for the linear() easing function, which as of right now is Chrome & Edge 113 + Firefox 112, Safari doesn't support it yet.

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

`bash
npm install
`

Then run tests

`bash
npm test
`

Build project

`bash
npm run build
`

> _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).

The CSSSpringEasing, getOptimizedPoints and getLinearSyntax functions from spring-easing which are used in postcss-spring-easing` are based of the work done by Jake Archibald in his Linear Easing Generator
and are thus licensed under the Apache License 2.0.