useAnimeTimeline
The useAnimeTimeline composable wraps the createTimeline function from AnimeJS.
It returns a proxied Timeline that accepts Vue template refs, component refs, and reactive targets in .add(), .set(), and .remove() calls. Calls made before mount are buffered and replayed once the DOM is ready.
Arguments
Example
ready
import { scrambleText } from '#nanime/proxies/text'
const box = useTemplateRef('box')
const label = useTemplateRef('label')
const tl = useAnimeTimeline({ loop: true })
tl
.add(box, { translateX: 250, duration: 800 })
.add(label, { innerHTML: scrambleText({ text: 'moved!' }) }, '<<')
.add({ duration: 500 })
.add(box, { rotate: 360, duration: 600 })
.add(label, { innerHTML: scrambleText({ text: 'spinning!' }) }, '<<')
.add({ duration: 500 })
.add(box, { translateX: 0, rotate: 0, duration: 800 })
.add(label, { innerHTML: scrambleText({ text: 'ready' }) }, '<<')
.add({ duration: 1000 })
<template>
<div
ref="box"
class="simple-box !size-8"
/>
<p
ref="label"
class="font-mono text-sm text-(--color-primary)"
>
ready
</p>
</template>
Syncing with other composables
Use .sync() to synchronise a timeline with another nanime composable's animation. The proxy is automatically unwrapped to the raw AnimeJS instance.
const circleAnimation = useAnimate('.circle', { x: '15rem' })
const tlA = useAnimeTimeline({ loop: true, alternate: true })
tlA
.sync(circleAnimation)
.add('.triangle', { x: '15rem', duration: 2000 })
.add('.square', { x: '15rem' })
.add({ duration: 1500 })
const tlB = useAnimeTimeline({
loop: true,
alternate: true,
defaults: {
duration: 2000,
},
})
tlB
.add(
['.triangle', '.square'],
{ rotate: 360 }, 0,
)
.add(
'.circle',
{ scale: [1, 1.5, 1] }, 0,
)
const tlMain = useAnimeTimeline({ loop: true, alternate: true })
tlMain.sync(tlA).sync(tlB, '-=2000')
<template>
<div class="flex flex-col gap-1 w-full">
<div class="triangle size-6 bg-primary" />
<div class="flex gap-1">
<div class="square size-6 rounded-sm bg-primary" />
<div class="circle size-6 rounded-full bg-primary" />
</div>
</div>
</template>
.triangle {
mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Cpath d='M4.72 31.235h22.56a2.75 2.75 0 0 0 2.393-4.105L18.175 6.838a2.5 2.5 0 0 0-4.35 0L2.327 27.13a2.75 2.75 0 0 0 2.392 4.105z'/%3E%3C/svg%3E") no-repeat 50% 50%;
mask-size: cover;
transform-origin: 50% 70%;
}
Return Value
Returns a proxied Timeline instance. All Timeline methods (.play(), .pause(), .seek(), .reverse(), etc.) are available directly on the return value.
Chainable methods (.add(), .set(), .play(), etc.) are always callable, even before mount. If the underlying instance doesn't exist yet the call is buffered and replayed once it's created, and the method still returns the proxy for chaining. Non-chainable member access before mount returns undefined at runtime.
API
Types
function useAnimeTimeline(
parameters?: MaybeRefOrGetter<TimelineParams>
): BufferedProxyReturns<Timeline>
Key methods
| Method | Description |
|---|---|
.add(targets, params, position?) | Add an animation to the timeline |
.add(timerParams, position?) | Add a timer (pause) to the timeline |
.set(targets, params, position?) | Set properties at a position |
.sync(animation, position?) | Sync with another animation |
.call(callback, position?) | Execute a callback at a position |
.label(name, position?) | Add a named position |
.remove(targets, property?) | Remove target animations |
See AnimeJS Timeline documentation for the full API.
Caveats
- Targets passed to
.add(),.set()and.remove()go through nanime's target resolver, so template refs, component refs, CSS selectors and DOM elements all work directly.
useAnimeTimeline synchronously in setup() for it to react to parameters
changes. Called from onMounted, a watcher, or a handler, it runs in
instant mode: the timeline is
created once and parameters are read only that first time.