An UI animation library designed for modern JS frameworks.
Open Demo (better for large screen)
npm install --save tween-here
It should support TypeScript out of the box. If not, please submit an issue.
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.
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.
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): TweenStateBy 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.
Achieve a high FPS by using FLIP technique.
Schedule all DOM operations into microtasks, so there should be little overhead from DOM reflow.
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.
Add document.
Support rotation.
Add more demos.
Add bindings for React/Angular/Vue.
MIT
All contributions are welcome.