@pinyin/tween-here

TweenHere

An UI animation library designed for modern JS frameworks.

Open Demo (better for large screen)

打开中文Readme

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:

<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, so the performance should be relatively good.

Design Target

Motions are important.

But they are hard to implement.

We've already had many web animation solutions that are both precise and powerful, like Popmotion and 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) 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.

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):

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.

getTweenState(element: HTMLElement): TweenState

By passing the return value from this helper function to tweenHere, 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.

Add bindings for React/Angular/Vue.

Similar Projects & Articles

FLIP Technique

react-flip-move

Flipping

react-flip-toolkit

License

MIT

All contributions are welcome.