# simple-spring

> A stripped-back spring animation library for high-frequency animations

Latest version **1.3.1** (published 2023-04-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-spring
pnpm add simple-spring
yarn add simple-spring
bun add simple-spring
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2023-04-26 |
| First published | 2019-10-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ryan King |
| Maintainers | ryki |
| Keywords | spring, animation, physics |

## Links

- npm: https://www.npmjs.com/package/simple-spring
- Repository: https://github.com/ryanking1809/simple-spring
- Homepage: https://github.com/ryanking1809/simple-spring#readme
- Issues: https://github.com/ryanking1809/simple-spring/issues
- npm.io page: https://npm.io/package/simple-spring

## Alternatives

- [@luma.gl/experimental](https://npm.io/package/@luma.gl/experimental.md) — 77.1K weekly downloads
- [persona-harness](https://npm.io/package/persona-harness.md) — 4.7K weekly downloads
- [@tsparticles/effect-bubble](https://npm.io/package/@tsparticles/effect-bubble.md) — 4.6K weekly downloads
- [f3d](https://npm.io/package/f3d.md) — 730 weekly downloads
- [spark-html-motion](https://npm.io/package/spark-html-motion.md) — 298 weekly downloads

## Recent versions

- 1.3.1 (latest) — 2023-04-26
- 1.3.0 — 2019-11-26
- 1.1.1 — 2019-11-26
- 1.1.0 — 2019-11-24
- 1.0.2 — 2019-10-23
- 1.0.1 — 2019-10-23
- 1.0.0 — 2019-10-23

## README

# simple-spring
A stripped-back spring animation library for high-frequency animations.

<p align="center">
	<a href="https://codesandbox.io/s/threejs-meshline-custom-spring-3-ypkxx"><img src="https://imgur.com/g8ts0vJ.gif" /></a>
</p>

Click example above to view the live code!

    npm install simple-spring

# How to use

#### Import Spring

```js
import { Spring } from 'simple-spring'
```

#### Create a Spring and set a Target Value

First we create a spring and set target value for it to animate to.

```js
const springValue = new Spring()
springValue.setTarget(100)
```

#### Start Animation

Then we start the animation which will begin animating the value towards the target.

```js
springValue.start()
```

#### Get Animated Value

We can retreive the animated value at any point in time via `getValue()`.

```js
springValue.getValue()
```

# API

`new Spring()` accepts an object with the following properties.

```js
const springValue = new Spring({
    value: 0, // initial value of Spring, Number or Array of Numbers
    target: 0, // target value of Spring, Number or Array of Numbers
    tension: 170, // spring tension value
    friction: 26, // spring friction value
    mass: 1, // spring mass value
    precision: 0.01, // precision - can be increased to optimise performance
    fps: 120,  // frame rate - can be redued to optimise performance
    onStart: null, // callback with value and spring instance as arguments, fires on animation start. eg. (value, spring) => function(value)
    onFrame: null, // callback with value and spring instance as arguments, fires on animation each frame. eg. (value, spring) => function(value)
    onRest: null, // callback with value and spring instance as arguments, fires when animations is stopped, pasued, or completed. eg. (value, spring) => function(value)
    onComplete: null // callback with value and spring instance as arguments, fires on animation completion. eg. (value, spring) => function(value)
})
```

These values can also be set after instanciation, eg. `springValue.onFrame = value => updateState(value)`

#### Animation controls

The following can be used to control the animation.

- `springValue.start()` - begins animation loop
- `springValue.complete()` - end animation loop, and sets value to the target
- `springValue.stop()` - stops animation loop, and sets velocity to 0
- `springValue.pause()` - stops animation loop, but retains velocity

---
_Source: https://npm.io/package/simple-spring · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._