useWaapi

Demo

Wraps Anime.js waapi.animate() into a Vue composable. The animation is driven by the browser's native Web Animations API, re-created reactively when the target or options change, and stopped automatically on unmount.

Usage

Basic animation

WARNING

useWaapi accepts native CSS property names and values (e.g. translate: "220px", opacity: 0) — not Anime.js shorthand transforms like translateX.

<script setup lang="ts">
import { useTemplateRef } from "vue"
import { useWaapi } from "@juleshry/vue-animejs"

const box = useTemplateRef("box")

const { play, pause, restart } = useWaapi(box, {
  translate: "220px",
  duration: 1000,
  ease: "ease-in-out",
  autoplay: false,
})
</script>

<template>
  <div ref="box" class="box" />

  <button @click="play">Play</button>
  <button @click="pause">Pause</button>
  <button @click="restart">Restart</button>
</template>

Reactive options

Put a ref straight into the options object. The whole options object can also be a ref, a computed or a getter, which is what you need for a derived value like the one below.

WARNING

Changing options recreates the animation from scratch with the new parameters.

<script setup lang="ts">
import { useTemplateRef, ref } from "vue"
import { useWaapi } from "@juleshry/vue-animejs"

const box = useTemplateRef("box")
const distance = ref(100)

useWaapi(box, () => ({
  translate: `${distance.value}px`,
  duration: 600,
  ease: "ease-out",
}))

function increase() {
  distance.value += 50
}
</script>

<template>
  <div ref="box" class="box" />
  <button @click="increase">Increase distance</button>
</template>

Using convertEase

Convert an Anime.js easing function to a WAAPI-compatible CSS easing string.

<script setup lang="ts">
import { useTemplateRef } from "vue"
import { useWaapi } from "@juleshry/vue-animejs"
import { eases } from "animejs"

const box = useTemplateRef("box")

const { play, convertEase } = useWaapi(box, {
  translate: "220px",
  duration: 800,
  ease: convertEase(eases.inOut("quad")),
  autoplay: false,
})
</script>

<template>
  <div ref="box" class="box" />
  <button @click="play">Play</button>
</template>

CSS selector target

You can pass any valid Anime.js DOMTargetsParam directly instead of a template ref.

<script setup lang="ts">
import { useWaapi } from "@juleshry/vue-animejs"

const { play } = useWaapi(".box", {
  rotate: "360deg",
  duration: 1000,
})
</script>

<template>
  <div class="box" />
  <button @click="play">Spin</button>
</template>

Array of targets

Pass an array of individual template refs to animate them together as a single group.

<script setup lang="ts">
import { useTemplateRef } from "vue"
import { useWaapi } from "@juleshry/vue-animejs"

const box1 = useTemplateRef("box1")
const box2 = useTemplateRef("box2")
const box3 = useTemplateRef("box3")

useWaapi([box1, box2, box3], {
  translate: "220px",
  duration: 600,
  ease: "ease-out",
})
</script>

<template>
  <div ref="box1" class="box" />
  <div ref="box2" class="box" />
  <div ref="box3" class="box" />
</template>

Type Declarations

For all available options, see the Anime.js WAAPI documentation.

Show Type Declarations

export interface UseWaapiReturn {
  /** The underlying Anime.js WAAPI animation instance. `undefined` until the target is available. */
  animation: Readonly<ShallowRef<WAAPIAnimation | undefined>>
  /** Resumes from a paused state. */
  resume: () => WAAPIAnimation | undefined
  /** Pauses the animation at the current position. */
  pause: () => WAAPIAnimation | undefined
  /** Toggles between forward and reverse direction. */
  alternate: () => WAAPIAnimation | undefined
  /** Starts or resumes the animation. */
  play: () => WAAPIAnimation | undefined
  /** Reverses playback direction. */
  reverse: () => WAAPIAnimation | undefined
  /** Seeks to a specific time (in ms). Accepts a reactive ref for the time value. */
  seek: (time: MaybeRef<number>, muteCallbacks?: MaybeRef<boolean>) => WAAPIAnimation | undefined
  /** Restarts the animation from the beginning. */
  restart: () => WAAPIAnimation | undefined
  /** Commits the current animated styles to the element's inline style, then cancels the animation. */
  commitStyles: () => WAAPIAnimation | undefined
  /** Jumps immediately to the end of the animation. */
  complete: () => WAAPIAnimation | undefined
  /** Stops the animation and removes it from the WAAPI engine. */
  cancel: () => WAAPIAnimation | undefined
  /** Cancels the animation and restores all animated properties to their original values. */
  revert: () => WAAPIAnimation | undefined
  /** Converts an Anime.js easing function to a CSS `cubic-bezier()` string usable by WAAPI. */
  convertEase: (fn: MaybeRef<EasingFunction>, samples?: MaybeRef<number>) => string
}

/**
 * Wraps Anime.js `waapi.animate()` into a Vue composable. Reactively re-creates the WAAPI animation when the target or options change, and stops it automatically on unmount.
 *
 * @param targets - The DOM element(s) to animate via WAAPI. Accepts a template ref, a CSS selector, a DOM element, a reactive ref to any of these, or an array of them.
 * @param options - Anime.js WAAPI animation parameters. Accepts a plain object, a ref / computed / getter, and refs as direct properties. Defaults to `{}`.
 */
export declare function useWaapi(
  targets: AnimationTargets,
  options?: MaybeRefOrGetter<MaybeRefOptions<WAAPIAnimationParams>>
): UseWaapiReturn

Reactivity Behavior

• The animation is created once the component has mounted, whatever form targets takes (template ref, selector, element), so a selector can point into the component's own template, and server-rendered HTML is never touched before hydration.
• A template ref that is still empty at mount (e.g. behind a v-if) creates the animation as soon as it resolves.
• If either targets or options changes, the current animation is reverted and a new one is created. For options, that means a new object in a ref / computed / getter, a ref inside it changing, or a property of a reactive object mutated in place.
• If targets resolves to nothing, a warning is logged and animation stays undefined.
• On component unmount, the watcher is stopped and the animation is cancelled automatically.

TIP

Always use useTemplateRef<HTMLElement>('refName') for DOM targets — not ref<HTMLElement | null>(null). The composable uses unrefElement from @vueuse/core to resolve it correctly.

WARNING

useWaapi uses native CSS property names. Use translate: "220px" instead of translateX: 220, and rotate: "360deg" instead of rotate: 360.

WARNING

animation is a readonly shallow ref. Do not mutate the WAAPI instance directly — use the returned control methods instead.

Source

use-waapi.ts