useWaapiAnimate

useWaapiAnimate wraps the waapi.animate function from AnimeJS. It animates DOM elements through the browser's Web Animations API instead of a JavaScript loop.

When target or reactive parameters change, nanime rebuilds the animation. It reverts when the component unmounts.

Usage

import { stagger } from '#nanime/utils'

const eases = ['outBack(3)', 'inOutExpo', 'outElastic(1, .5)', 'steps(6)']

const boxes = useTemplateRef('boxes')
const ease = ref<string>(eases[0])

useWaapiAnimate(boxes, () => ({
  transform: ['translateY(-24px)', 'translateY(0px)'],
  ease: ease.value,
  duration: 1000,
  delay: stagger(80),
  alternate: true,
  loop: true,
}))

<template>
  <div class="flex gap-2.5 pt-6">
    <div
      v-for="i in 6"
      ref="boxes"
      :key="i"
      class="size-8 rounded-lg bg-primary"
    />
  </div>
</template>

Signature

function useWaapiAnimate(
  target: WaapiTargets,
  parameters?: MaybeRefOrGetter<WAAPIAnimationParams>
): WAAPIAnimation

Parameters

Returns

Returns a reactive proxy around the AnimeJS WAAPIAnimation. Its methods and properties are in the AnimeJS WAAPI documentation. Call methods on the returned object, as in animation.play(), because a destructured method throws. progress doesn't update a template either.

Caveats

Do not destructure the returned instance

// wrong: play() throws when called
const { play } = useWaapiAnimate('.target', parameters)

// right
const animation = useWaapiAnimate('.target', parameters)
animation.play()

The proxy hands back methods without their instance, so a destructured play() runs with no this and throws. A destructured property such as progress is a copy of the value at that moment. Keep the returned object and call methods on it.

Properties do not update templates

// wrong: progress never updates inside a template interpolation
// <p>{{ animation.progress }}</p>

Interpolating properties like progress in a template displays only their initial value. WAAPIAnimation has no per-frame callback, so nothing tells Vue when progress changes. useAnimate runs its own render loop and exposes an onUpdate callback instead, so reach for it when a template needs to track progress live.

Type reference

type WaapiElementTargets = VueInstance | HTMLElement | HTMLElement[] | SVGElement | SVGElement[] | NodeList | string | null
type WaapiTargets = MaybeRef<WaapiElementTargets> | MaybeRef<WaapiElementTargets>[]

See also

• useAnimate: Main-thread animation engine supporting SVG morphing and JS objects
• Performance guide: Guidance on choosing between WAAPI and requestAnimationFrame
• AnimeJS WAAPI documentation: Upstream parameters and browser requirements