# @pinyin/tween-here

> An animation library designed for modern JS frameworks.

Latest version **0.0.36** (published 2018-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @pinyin/tween-here
pnpm add @pinyin/tween-here
yarn add @pinyin/tween-here
bun add @pinyin/tween-here
```

## Health

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

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

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.36 |
| Published | 2018-07-22 |
| First published | 2018-05-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 87.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Bo Bao |
| Maintainers | pinyin |
| Keywords | tweening, animation, transform, FLIP, CSS |

## Links

- npm: https://www.npmjs.com/package/@pinyin/tween-here
- Repository: https://github.com/pinyin/tween-here
- Homepage: https://github.com/pinyin/tween-here#readme
- Issues: https://github.com/pinyin/tween-here/issues
- npm.io page: https://npm.io/package/@pinyin/tween-here

## Dependencies (7)

- [tslib](https://npm.io/package/tslib.md) ^1.9.3
- [@pinyin/dom](https://npm.io/package/@pinyin/dom.md) ^0.0.12
- [@pinyin/frame](https://npm.io/package/@pinyin/frame.md) ^0.0.14
- [@pinyin/maybe](https://npm.io/package/@pinyin/maybe.md) ^0.0.9
- [@pinyin/types](https://npm.io/package/@pinyin/types.md) ^0.0.45
- [@pinyin/outline](https://npm.io/package/@pinyin/outline.md) 0.0.16
- [synchronous-promise](https://npm.io/package/synchronous-promise.md) ^2.0.5

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 0.0.36 (latest) — 2018-07-22
- 0.0.35 — 2018-07-22
- 0.0.34 — 2018-07-22
- 0.0.33 — 2018-07-19
- 0.0.32 — 2018-07-18
- 0.0.31 — 2018-07-18
- 0.0.30 — 2018-07-16
- 0.0.29 — 2018-07-16
- 0.0.28 — 2018-07-15
- 0.0.27 — 2018-07-14
- 0.0.26 — 2018-07-14
- 0.0.24 — 2018-07-13
- 0.0.23 — 2018-07-12
- 0.0.22 — 2018-07-11
- 0.0.21 — 2018-07-11
- … 19 more at https://npm.io/package/@pinyin/tween-here/versions

## README

# TweenHere

[![Build Status](https://travis-ci.org/pinyin/tween-here.svg?branch=master)](https://travis-ci.org/pinyin/tween-here)

An UI animation library designed for modern JS frameworks.

[Open Demo (better for large screen)](http://pinyin.github.io/tween-here)

[打开中文Readme](./README.cn.md)

## Install

`npm install --save tween-here`

It should support TypeScript out of the box. If not, please submit an issue.

## Usage

TweenHere is designed for UI animations. 

For example, if you want to change the scroll position of a scroll container:

```html
<div style="overflow-y: scroll"> // scroll container element
    <div id="content"> // content element
    // ... elements
    </div>
</div>
```
To adjust its scroll position, you will:
```
container.scrollTop = 100
```
Content will then jump to a new position. What if you want it to move smoothly? 

With TweenHere, you can add an animation within three lines:
```
const content = document.getElementById('content')
const snapshot = getTweenState(content) // get position of scrolled content
container.scrollTop = 100
tweenHere(content, snapshot) // content will move to its new position smoothly 
```

... and you can achieve a surprising number of effects with this simple API.

All animations are implemented with [FLIP technique](https://aerotwist.com/blog/flip-your-animations/), so the performance should be relatively good.

## Design Target

[Motions are important](https://material.io/guidelines/motion/material-motion.html#material-motion-why-does-motion-matter).

But they are hard to implement.

We've already had many web animation solutions that are both precise and powerful, like [Popmotion](https://popmotion.io/) and [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) and many other awesome ones, but sometimes, even these precise solutions seem to be too much work compared to the simple use case.

> "Just make this element appear smoothly, please. It should be simple."  - your product manager

That's what `TweenHere` is designed for: UI animations. It does not aim to be a library that enables any animation, but you should be able to implement most UI motions (like the ones from [Material Design](https://material.io/guidelines/motion/material-motion.html)) with this library.

With `TweenHere`, instead of specifying a start state and a end state, an animation is regarded as "how an element comes to its current state", so it should work with most JS frameworks: as long as you can get the reference to a DOM node, you can animate it.

## APIs

`TweenHere` comes with two functions, `tweenHere` and `tweenExit`, each function provides a fast way to implement a kind of motions. 

```typescript jsx

async function tweenHere(
    element: HTMLElement,
    from: TweenState | ((snapshot: TweenState, to: TweenState) => TweenState),
    params?: {
        duration?: number | ((from: TweenState, to: TweenState) => number),
        easing?: [number, number, number, number],
        fixed?: boolean,
    }
): Promise<void> 

async function tweenExit(
    element: HTMLElement,
    to: TweenState | ((from: TweenState) => TweenState),
    params?: {
        duration?: number | ((from: TweenState, to: TweenState) => number),
        easing?: [number, number, number, number],
        container?: Element,
        fixed?: boolean,
    }
): Promise<void> 
```

For both function, only the first two params are necessary.

TweenState is an object representing the properties of an element (relative to viewport):
```typescript jsx
type TweenState = {
    x: number
    y: number
    width: number
    height: number
    opacity: number
} 
```
You can get these numbers manually with `getBoundingClientRect()` and other native APIs. 

For convenience, this library provides a helper function, `getTweenState`, to construct a `TweenState` from an existing element. 

```typescript jsx
getTweenState(element: HTMLElement): TweenState
```

[By passing the return value from this helper function to `tweenHere`](demo/OpenListItem.tsx), you can easily make an element appear smoothly from the position of another element, constructing a visual effect that they are the same element.

In general, use `tweenHere` when you want an element to move to its current state smoothly, use `tweenExit` on an element when you know the element will be detached from document and want it to disappear smoothly.

## Features

Achieve a high FPS by using FLIP technique.

Schedule all DOM operations into microtasks, so there should be little overhead from DOM reflow.

## Limits

The animated element's `transform` `opacity` and `transition` style properties are not preserved.

`tweenExit` adds node to the DOM structure while tweening, so it may not be capable with some CSS styles.

This library is still at its early stage, please report an issue if you notice any undesired behavior.

Requires `WeakMap`, `Set` and `MutationObserver` to be present in runtime. Polyfills are ok.

## Plans

Add document.

Support rotation.

Add more [demos](http://pinyin.github.io/tween-here).

Add bindings for React/Angular/Vue.

## Similar Projects & Articles

[FLIP Technique](https://aerotwist.com/blog/flip-your-animations/)

[react-flip-move](https://github.com/joshwcomeau/react-flip-move)

[Flipping](https://github.com/davidkpiano/flipping)

[react-flip-toolkit](https://github.com/aholachek/react-flip-toolkit)

## License

MIT

All contributions are welcome.

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