useAni

This composable subscribes to a timeline's state and updates a Vue ref on each animation frame. It's ideal when animated values need to be read within your component's template or other reactive computations.

Example

<script setup>
import { a } from "@freestylejs/ani-core";
import { useAni } from "@freestylejs/ani-vue";

// 1. Define the animation structure and create a timeline.
const myTimeline = a.dynamicTimeline(
  a.ani({ to: { count: 100 }, duration: 5, timing: a.timing.linear() })
);

// 2. Use the composable to get the reactive ref and controller.
const [value, controller] = useAni(myTimeline, { count: 0 });

// 3. Play the animation.
function handlePlay() {
  controller.play({ from: { count: 0 } });
}
</script>

<template>
  <div>
    <!-- 4. The ref's value is automatically unwrapped in the template. -->
    <h1>Counter: {{ Math.round(value.count) }}</h1>
    <button @click="handlePlay">Start</button>
  </div>
</template>

Usage & Concepts

Overview

The useAni composable acts as a bridge between the @freestylejs/ani-core engine and Vue's reactivity system. It takes a timeline instance and an initialValue, returning a reactive Vue ref that is updated with the latest animation value, alongside the timeline's controller. Vue's reactivity system automatically tracks this ref and updates the component whenever its value changes.

When to Use

• Do use useAni when you need the animated values to be part of Vue's reactive system.
• Do use it for animations that affect text content, attributes, or props.
• Don't use useAni for high-frequency style updates on a single element. For that, useAniRef is a better choice.

Related Components

• useAniRef - For performance-critical animations that write directly to the DOM.
• timeline - The core controller that this composable subscribes to.