# @smoovy/tween

> simple and easy-to-use tween lib

Latest version **1.1.28** (published 2025-11-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @smoovy/tween
pnpm add @smoovy/tween
yarn add @smoovy/tween
bun add @smoovy/tween
```

## Health

**Score 55/100 (C)** — status: stable.

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

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.28 |
| Published | 2025-11-14 |
| First published | 2019-05-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 52.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 86 |
| Author | Davide Perozzi |
| Maintainers | davideperozzi |
| Keywords | tween, smoovy, ticker |

## Links

- npm: https://www.npmjs.com/package/@smoovy/tween
- Repository: https://github.com/davideperozzi/smoovy
- Issues: https://github.com/davideperozzi/smoovy/issues
- npm.io page: https://npm.io/package/@smoovy/tween

## Dependencies (1)

- [@smoovy/ticker](https://npm.io/package/@smoovy/ticker.md) ^1.0.2

## Recent versions

- 1.1.28 (latest) — 2025-11-14
- 1.1.27 — 2024-11-29
- 1.1.26 — 2024-11-26
- 1.1.25 — 2024-10-28
- 1.1.24 — 2024-04-23
- 1.1.23 — 2023-12-02
- 1.1.22 — 2023-11-19
- 1.1.21 — 2023-11-19
- 1.1.20 — 2023-11-15
- 1.1.19 — 2023-11-13
- 1.1.18 — 2023-11-12
- 1.1.17 — 2023-11-12
- 1.1.16 — 2023-11-12
- 1.1.15 — 2023-11-12
- 1.1.14 — 2023-11-09
- … 31 more at https://npm.io/package/@smoovy/tween/versions

## README

# @smoovy/tween
[![Version](https://flat.badgen.net/npm/v/@smoovy/tween)](https://www.npmjs.com/package/@smoovy/tween) ![Size](https://flat.badgen.net/bundlephobia/minzip/@smoovy/tween)

A small and easy-to-use tween engine built on top of [@smoovy/ticker](../ticker/README.md). It's meant to be simple and not include too many edge cases. So basically tween values. It supports *fromTo*, *timelines*, *stagger* etc. like many animation libraries.

## Installation
```sh
yarn add @smoovy/tween
```
or
```sh
npm install --save @smoovy/tween
```

## Usage
Import the `tween` method:
```js
import { tween } from '@smoovy/tween';
```

### Starting a simple tween
Every tween is going to be started with the `fromTo` function:

```js
tween.to(
  { x: 0 },
  { x: 100 },
  {
    duration: 200,
    on: {
      update: ({ x }) => {
        // Do something with "x"
      }
    }
  }
);
```

### Using easings
The following easing functions are supported out-of-the-box:

```js
import { easings } from '@smoovy/easings';

easings.easeInOutBounce
easings.easeInExpo
...
```

To use one of these, you can just add it to the tween options:

```js
tween.to(
  { x: 0 },
  { x: 100 },
  {
    duration: 200,
    easing: easings.ExpoOut
  }
);
```
> The default easing is linear: `(x) => x`

You can implment your own easing functions. Just follow this pattern:
```ts
type Easing = (x: number) => number
```

### Object mutation
By default the object you're passing as an "input" will be mutated.
To prevent mutation, you need to disable it:

```js
const someValues = { x: 0, y: 0 };

tween.to(
  someValues,
  { x: 100, y: 100 },
  {
    duration: 200,
    mutate: false,
    on: {
      update: (values) => {
        // someValues.x is still 0
      }
    }
  }
);
```

### Apply changes to the DOM directly
Supports `opacity` and all `transforms`

```js
const element = document.querySelector('.target');

tween.to(
  element,
  { x: 100, y: 100 },
  { duration: 200 }
);

// rotate and move
tween.to(
  element,
  { x: 100, rotate: 100 },
  { duration: 200 }
);

// change the units to use
tween.to(
  element,
  { y: 100 },
  {
    duration: 200,
    units: { y: '%' }
  }
);
```

### Stagger

```js
const elements = document.querySelectorAll('.target');

tween.staggerTo(
  element,
  { x: 100, y: 100 },
  {
    stagger: {
      // determines the intersection perecentage between each tween
      // it uses the neighbors duration so you don't have to keep track
      // of the duration yourself. This makes all items start 30% before
      // the end of the next tween
      offeset: -0.3,

      // this would start all simultaneously
      // offset: -1.0
    },
    timline: {
      onComplete: () => console.log('all tweens complete')
    }
    // ... same properties as above
  }
);
```

### Timeline
```js
const element1 = document.querySelectorAll('.target1')
const element2 = document.querySelectorAll('.target2')
const timeline = tween.timeline({
  onComplete: () => conosole.log('timeline completed')
});

timeline.add(tween.to(
  element1,
  { x: 100, y: 100 },
  { duration: 200 }
))
timeline.add(tween.to(
  element2,
  { x: 100, y: 100 },
  { duration: 200 }
), {
  offset: -0.2 // start 20% before element1 has finished (overlap)
});

timeline.start();
```

### Promisified
All tweens, staggers and timelines can be awaited.

```js
const tween1 = await tween.to(
  { x: 0 },
  { x: 100 },
  {
    duration: 200,
    easing: easings.ExpoOut
  }
);

// will be reversed and repeated once the first anaimation is done
tween1.resverse().start();
```

### Infinite repetition
There's no option for that, but you can combine `onComplete` and `start`:

```js
// this will loop idefinitely between 0 and 100 (back and forth)
// you can remove `reverse` to so it always goes form 0 to 100
const tween1 = tween.to(
  { x: 0 },
  { x: 100 },
  {
    duration: 200,
    easing: easings.ExpoOut,
    onComplete: () => tween1.reverse().start()
  }
);
```

### All the tween options
Below are all the available tween options.
> `Values` represents the input type
```ts
// An easing implementation
// Default: Circ.out
easing: EasingImplementation;

// The duration in milliseconds
// Default: 0
duration: number;

// Prevent object mutation
// Default: true
mutate: boolean;

// Overwrite tween for same object reference
// Default: true
overwrite: boolean;

// Delay before start (in ms)
delay: number;

// Determines if the tween should start immediately
// Default: true
autoStart: boolean;

// All callbacks (optional)
onStop: () => void;
onPause: () => void;
onStart: () => void;
onReset: () => void;
onDelay: (passed: number, progress: number) => void;
onUpdate: (values: Values, progress: number, target: HTMLElement) => void;
onOverwrite: () => void;
onComplete: () => void;
```

## License
See the [LICENSE](../../LICENSE) file for license rights and limitations (MIT).

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