useAnimeTimeline
useAnimeTimeline wraps the createTimeline
function from AnimeJS. It plays a sequence of animations on one clock, so
the whole sequence plays, pauses and seeks together.
When reactive parameters change, nanime rebuilds the timeline and adds the
same steps again. By default it restarts. Set keepTime: true to carry the
playhead over instead.
Usage
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>
Signature
function useAnimeTimeline(
parameters?: MaybeRefOrGetter<TimelineParams>,
options?: NanimeInstanceOptions
): BufferedProxyReturns<Timeline>
Parameters
ref or a getter. The timeline rebuilds when it
changes. See the
AnimeJS timeline documentation
for the options.useAnimeScroll result can go straight into autoplay. nanime passes
AnimeJS the observer inside it.| Option | Type | Default |
|---|---|---|
keepTime | boolean | false |
Returns
Returns a buffered proxy around the AnimeJS Timeline.
Its methods and properties are in the
AnimeJS timeline documentation.
The members nanime changes:
| Member | Type | Notes |
|---|---|---|
add(targets, params, position?) | (...) => this | targets also accepts template refs and component refs. Runs again on every rebuild. |
set(targets, params, position?) | (...) => this | targets also accepts template refs and component refs. Runs again on every rebuild. |
remove(targets, propertyName?) | (...) => this | targets also accepts template refs and component refs. Runs again on every rebuild. |
sync(animation, position?) | (...) => this | animation also accepts the value returned by useAnimate or useWaapiAnimate. Runs again on every rebuild. |
label(), call(), stretch() | (...) => this | Run again on every rebuild. |
The timeline is created when the component mounts. Methods can be called
straight from setup(), and run at that point. Playback methods such as
play() run once and are not repeated on a rebuild. Read properties such
as currentTime after mount.
Caveats
Read properties after mount
// wrong: currentTime is undefined before mount
const tl = useAnimeTimeline()
console.log(tl.currentTime) // undefined
// right: read timeline properties after mount
onMounted(() => {
console.log(tl.currentTime)
})
The underlying Timeline instance is created after mount, or immediately
in Instant mode. Chainable
methods such as add(), play(), and pause() buffer safely before
that and replay in sequence, but non-chainable property reads return
undefined until the timeline instance exists. Access inspection properties
after mount.
Type reference
interface NanimeInstanceOptions {
keepTime?: boolean
}
type BufferedProxyReturns<T> = Exclude<UnwrapNestedRefs<T>, null | undefined>
See also
useAnimate: individual animation composable- AnimeJS timeline documentation: upstream positioning syntax and timing offsets