Composables

Composable lifecycle

Where a nanime composable builds, when it rebuilds, and the caveats that apply across all of them.

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.ts defaults, provideAnimeDefaults() and presets do not apply.
  • reducedMotion is 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())
A top-level 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 a TypeError.
  • A property read gives undefined.
ComposableQueued before mount
useAnimeTimelineadd, set, remove, call, label, sync, stretch, refresh, revert and the playback methods play, pause, resume, restart, reset, reverse, alternate, seek, cancel, complete, init, resetTime
useDraggabledisable, enable, reset, revert, stop, setX, setY, scrollInView, animateInView
useAnimeScrolllink, refresh, revert
useAnimeLayoutrecord

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:

ComposableRebuilds when
useAnimatabletarget changes. Its options are read once.
useDraggabletarget or trigger changes. A new container or a ref in the listed options updates it in place.
useAnimeScrolltarget 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.

Vue changes the array in 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

Toast.vue
<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.

Two composables do rebuild on a callback change: 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 progress is copied once and never updates.
  • A useAnimatable setter such as x keeps working, but after target changes 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,
})
useWaapiAnimate has no onUpdate. Use useAnimate when a template needs live 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 })
Copyright © 2026