---
title: "Composable lifecycle"
description: "Where a nanime composable builds, when it rebuilds, and the caveats that apply across all of them."
canonical_url: "https://nanimejs.netlify.app/composables/composable-lifecycle"
---
# 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](https://nanimejs.netlify.app/composables/introduction) covers its own API. The
experimental [`useWaapiTimeline`](https://nanimejs.netlify.app/composables/use-waapi-timeline) 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](https://nanimejs.netlify.app/composables/introduction#choosing-a-composable) 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()`](https://nanimejs.netlify.app/guides/defaults#scope-defaults-to-part-of-the-app) 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:

```ts
const animation = useAnimate('.box', { opacity: [0, 1], autoplay: false })

button.addEventListener('click', () => animation.play())
```

<note>

A top-level `await` in `<script setup>` still counts as `setup()`.

</note>

### 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`.

<table>
<thead>
  <tr>
    <th align="left">
      Composable
    </th>
    
    <th align="left">
      Queued before mount
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      <code>
        useAnimeTimeline
      </code>
    </td>
    
    <td align="left">
      <code>
        add
      </code>
      
      , <code>
        set
      </code>
      
      , <code>
        remove
      </code>
      
      , <code>
        call
      </code>
      
      , <code>
        label
      </code>
      
      , <code>
        sync
      </code>
      
      , <code>
        stretch
      </code>
      
      , <code>
        refresh
      </code>
      
      , <code>
        revert
      </code>
      
       and the playback methods <code>
        play
      </code>
      
      , <code>
        pause
      </code>
      
      , <code>
        resume
      </code>
      
      , <code>
        restart
      </code>
      
      , <code>
        reset
      </code>
      
      , <code>
        reverse
      </code>
      
      , <code>
        alternate
      </code>
      
      , <code>
        seek
      </code>
      
      , <code>
        cancel
      </code>
      
      , <code>
        complete
      </code>
      
      , <code>
        init
      </code>
      
      , <code>
        resetTime
      </code>
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        useDraggable
      </code>
    </td>
    
    <td align="left">
      <code>
        disable
      </code>
      
      , <code>
        enable
      </code>
      
      , <code>
        reset
      </code>
      
      , <code>
        revert
      </code>
      
      , <code>
        stop
      </code>
      
      , <code>
        setX
      </code>
      
      , <code>
        setY
      </code>
      
      , <code>
        scrollInView
      </code>
      
      , <code>
        animateInView
      </code>
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        useAnimeScroll
      </code>
    </td>
    
    <td align="left">
      <code>
        link
      </code>
      
      , <code>
        refresh
      </code>
      
      , <code>
        revert
      </code>
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        useAnimeLayout
      </code>
    </td>
    
    <td align="left">
      <code>
        record
      </code>
    </td>
  </tr>
</tbody>
</table>

### 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`:

```ts
const draggable = useDraggable('.card')

onMounted(async () => {
  await nextTick()
  console.log(draggable.x)
})
```

<note>

`useAnimeLayout` builds during mount, so its members are ready inside
`onMounted` without `nextTick()`.

</note>

### 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`](https://nanimejs.netlify.app/guides/configuration#set-module-options) 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:

<table>
<thead>
  <tr>
    <th align="left">
      Composable
    </th>
    
    <th align="left">
      Rebuilds when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      <code>
        useAnimatable
      </code>
    </td>
    
    <td align="left">
      <code>
        target
      </code>
      
       changes. Its options are read once.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        useDraggable
      </code>
    </td>
    
    <td align="left">
      <code>
        target
      </code>
      
       or <code>
        trigger
      </code>
      
       changes. A new <code>
        container
      </code>
      
       or a <code>
        ref
      </code>
      
       in the listed options updates it in place.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        useAnimeScroll
      </code>
    </td>
    
    <td align="left">
      <code>
        target
      </code>
      
       or <code>
        container
      </code>
      
       changes, or a field of its <code>
        reactive()
      </code>
      
       object changes. It takes a plain or <code>
        reactive()
      </code>
      
       object, not a <code>
        ref
      </code>
      
       or getter.
    </td>
  </tr>
</tbody>
</table>

### Animate items added to a `v-for` list

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

<note>

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](https://github.com/vuejs/core/pull/12733).
Call `toRaw(cards.value)` where you need a plain array.

</note>

### Read changing values inside callbacks

```vue [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.

<note>

Two composables do rebuild on a callback change: `useWaapiAnimate` on any
function except `onComplete`, and `useScrambleText` on callbacks in
`scrambleOptions`.

</note>

## Avoid common mistakes

### Do not destructure the returned instance

Applies to `useAnimate`, `useWaapiAnimate`, `useAnimatable` and
`useScrambleText`.

```ts
// 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.

```ts
const progress = ref(0)
const animation = useAnimate('.target', {
  opacity: [0, 1],
  // wrong: {{ animation.progress }}
  onUpdate: self => progress.value = self.progress,
})
```

<note>

`useWaapiAnimate` has no `onUpdate`. Use
[`useAnimate`](https://nanimejs.netlify.app/composables/use-animate) when a template needs live
progress.

</note>

### Plain object targets must be reactive

Applies to `useAnimate` and `useAnimatable`.

```ts
// 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 })
```


## Sitemap

See the full [sitemap](https://nanimejs.netlify.app/sitemap.md) for all pages.
