Composable lifecycle
The nine AnimeJS composables share the same rules for building, rebuilding
and tearing down their AnimeJS instance. Each
composable page covers its own API. The
experimental useWaapiTimeline never
rebuilds, and its page covers when it builds.
Where you can call a composable
Call a composable in setup() unless you have a reason not to. The
composables index marks
which composables have Instant play and which are Buffered.
Instant play
Composables with Instant play also work outside setup(), for example in
a click handler. There they build the animation on the next tick, or at the
first playback call for useWaapiTimeline, and read parameters once, so later ref changes are ignored. Outside setup()
there is no component to read from, so:
app.config.tsdefaults,provideAnimeDefaults()and presets do not apply.reducedMotionis not honored, so the animation always plays.- Nothing reverts the animation. Call
revert()yourself, or each call stacks another animation on the same targets.
To keep reactivity, call the composable in setup() and call play() on
the returned object from the handler. useAnimate autoplays on mount, so
set autoplay: false when the handler starts the animation:
const animation = useAnimate('.box', { opacity: [0, 1], autoplay: false })
button.addEventListener('click', () => animation.play())
await in <script setup> still counts as setup().Buffered
Buffered composables build their instance after the component mounts, so
in setup():
- A call to a method in the table below is queued and replayed in order once the instance exists.
- Any other method is
undefined, so calling it throws aTypeError. - A property read gives
undefined.
| Composable | Queued before mount |
|---|---|
useAnimeTimeline | add, set, remove, call, label, sync, stretch, refresh, revert and the playback methods play, pause, resume, restart, reset, reverse, alternate, seek, cancel, complete, init, resetTime |
useDraggable | disable, enable, reset, revert, stop, setX, setY, scrollInView, animateInView |
useAnimeScroll | link, refresh, revert |
useAnimeLayout | record |
Read properties after mount
useAnimeTimeline, useDraggable and useAnimeScroll build their
instance on the tick after the component mounts. Read properties after
await nextTick() inside onMounted, or inside a callback such as
onDrag:
const draggable = useDraggable('.card')
onMounted(async () => {
await nextTick()
console.log(draggable.x)
})
useAnimeLayout builds during mount, so its members are ready inside
onMounted without nextTick().Composables that are not Buffered
useAnimate, useWaapiAnimate and useScrambleText return an empty
placeholder until the component mounts, so a method called during
setup() does nothing. useAnimatable has no setters until then, so
calling one throws.
Know when an animation rebuilds
By default a rebuild reverts the old instance and builds a new one, so the
animation restarts. Set
rebuild to 'keepTime' to
continue from the playhead, or to 'keepValue' (useAnimate only) to
cancel the old instance and start from the current values.
Most composables rebuild when target or a parameter changes. Three differ:
| Composable | Rebuilds when |
|---|---|
useAnimatable | target changes. Its options are read once. |
useDraggable | target or trigger changes. A new container or a ref in the listed options updates it in place. |
useAnimeScroll | target or container changes, or a field of its reactive() object changes. It takes a plain or reactive() object, not a ref or getter. |
Animate items added to a v-for list
<script setup lang="ts">
const items = ref([1, 2, 3])
const cards = useTemplateRef('cards')
useAnimate(cards, { y: -16, alternate: true, loop: true })
</script>
<template>
<div v-for="item in items" :key="item" ref="cards" />
</template>
Adding to or removing from items rebuilds the animation with the new
list of cards. Pass the ref itself, not cards.value or a getter, to
useAnimate, useWaapiAnimate, useAnimatable, useScrambleText or
useDraggable. useAnimeTimeline reads the targets of each add() once,
when you call it.
cards.value in place, which no watcher can
detect. nanime makes that array shallowReactive(), as Vue plans to do
in vuejs/core#12733.
Call toRaw(cards.value) where you need a plain array.Read changing values inside callbacks
<script setup lang="ts">
const props = defineProps<{ onDone: () => void }>()
const toast = useTemplateRef('toast')
useAnimate(toast, () => ({
opacity: 0,
delay: 3000,
// wrong: onComplete: props.onDone
onComplete: () => props.onDone(),
}))
</script>
<template>
<div ref="toast">Saved</div>
</template>
Changing only a callback does not rebuild the animation, so read changing values inside it.
useWaapiAnimate on any
function except onComplete, and useScrambleText on callbacks in
scrambleOptions.Avoid common mistakes
Do not destructure the returned instance
Applies to useAnimate, useWaapiAnimate, useAnimatable and
useScrambleText.
// wrong: play() throws when called
const { play } = useAnimate('.target', { opacity: 0 })
// right
const animation = useAnimate('.target', { opacity: 0 })
animation.play()
Destructured properties and setters break too:
- A property such as
progressis copied once and never updates. - A
useAnimatablesetter such asxkeeps working, but aftertargetchanges it still animates the old target.
Properties do not update templates
Applies to every composable except useSplitText, which returns refs, and
useAnimatable, which returns setters.
const progress = ref(0)
const animation = useAnimate('.target', {
opacity: [0, 1],
// wrong: {{ animation.progress }}
onUpdate: self => progress.value = self.progress,
})
Plain object targets must be reactive
Applies to useAnimate and useAnimatable.
// AnimeJS writes to a plain object directly, so Vue never sees the change
const position = { x: 0, y: 0 }
useAnimate(position, { x: 100 })
// reactive(), shallowReactive() and ref() work, a shallowRef holding an object does not
const tracked = reactive({ x: 0, y: 0 })
useAnimate(tracked, { x: 100 })