---
title: "Performance"
description: "Make nanime do less work on each render, each frame and each animation."
canonical_url: "https://nanimejs.netlify.app/guides/performance"
---
# Performance

> Make nanime do less work on each render, each frame and each animation.

Each tip makes `nanime` do less work.

<table>
<thead>
  <tr>
    <th align="left">
      Tip
    </th>
    
    <th align="left">
      Applies to
    </th>
    
    <th align="left">
      What to do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      <a href="#add-deps-to-groups">
        Group <code>
          deps
        </code>
      </a>
    </td>
    
    <td align="left">
      <code>
        <AnimeTransitionGroup>
      </code>
      
      , <code>
        <AnimeLayoutGroup>
      </code>
    </td>
    
    <td align="left">
      Pass <code>
        deps
      </code>
      
       so a group measures only when its state changes.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#keep-group-items-small">
        Group size
      </a>
    </td>
    
    <td align="left">
      <code>
        <AnimeTransitionGroup>
      </code>
      
      , <code>
        <AnimeLayoutGroup>
      </code>
    </td>
    
    <td align="left">
      Keep the part that moves small.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#run-simple-animations-off-the-main-thread">
        WAAPI
      </a>
    </td>
    
    <td align="left">
      <code>
        useWaapiAnimate
      </code>
    </td>
    
    <td align="left">
      Use it for <code>
        transform
      </code>
      
       and <code>
        opacity
      </code>
      
       animations.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#use-useanimatable-for-constant-values">
        Constant values
      </a>
    </td>
    
    <td align="left">
      <code>
        useAnimatable
      </code>
    </td>
    
    <td align="left">
      Tween from the current value instead of restarting an animation.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#split-text-by-words-or-lines">
        Text
      </a>
    </td>
    
    <td align="left">
      <code>
        useSplitText
      </code>
    </td>
    
    <td align="left">
      Split headings by words or lines, not characters.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#target-elements-with-template-refs">
        Targets
      </a>
    </td>
    
    <td align="left">
      Every composable
    </td>
    
    <td align="left">
      Pass a template ref, not a selector string.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="#animate-transform-and-opacity">
        Properties
      </a>
    </td>
    
    <td align="left">
      Every composable
    </td>
    
    <td align="left">
      Animate <code>
        transform
      </code>
      
       and <code>
        opacity
      </code>
      
      , not layout properties.
    </td>
  </tr>
</tbody>
</table>

<note>

A hidden tab is a correctness problem, not a performance one. AnimeJS
pauses every animation while the tab is hidden, so an exit can stay
mid-way. Set `completeOnTabHidden` on a component when that matters.
[Transition](https://nanimejs.netlify.app/components/transition#finish-animations-when-the-tab-is-hidden)
covers the prop.

</note>

## Tips

### Add `deps` to groups

Pass `deps` to every `<AnimeTransitionGroup>` and `<AnimeLayoutGroup>`.
Without it, a transition group measures every element inside it, and a
layout group records and animates on every re-render, even when nothing
moved.

```vue [CardList.vue]
<template>
  <AnimeTransitionGroup :deps="[]">
    <Card v-for="card in cards" :key="card.id" :card="card" />
  </AnimeTransitionGroup>
</template>
```

On an `<AnimeTransitionGroup>`, `:deps="[]"` makes the group measure only
when items are added, removed or reordered. Add the values that change an
item's size to the list, such as `:deps="[view]"`.

An `<AnimeLayoutGroup>` animates only when a value in `deps` changes. List
the state that changes its layout, as in `:deps="[expanded]"`. With
`:deps="[]"` it never animates.

A function entry is read as a getter, so it follows the value it returns:

```vue [ViewToggle.vue]
<template>
  <AnimeTransitionGroup :deps="[() => state.view]" shallow>
    <Card v-for="card in cards" :key="card.id" :card="card" />
  </AnimeTransitionGroup>
</template>
```

Add `shallow` when a `deps` entry is a large object. The group then
animates when the entry is replaced, not when something inside it changes.

### Keep group items small

A group measures every element inside it each time its items move. In a
group of 12 cards with about 20 elements each, one move measures all 240
elements. If the items of an `<AnimeTransitionGroup>` only enter and
leave, turn moves off so the group measures nothing:

```vue [Feed.vue]
<template>
  <AnimeTransitionGroup :move-animation="false">
    <Post v-for="post in posts" :key="post.id" :post="post" />
  </AnimeTransitionGroup>
</template>
```

For an `<AnimeLayoutGroup>`, pass `elements` so only the cards animate
while everything else in the group stays put:

```vue [Dashboard.vue]
<template>
  <AnimeLayoutGroup elements=".card">
    <Card v-for="card in cards" :key="card.id" :card="card" />
  </AnimeLayoutGroup>
</template>
```

[Choose which elements animate](https://nanimejs.netlify.app/components/layout-group#choose-which-elements-animate)
covers `elements` in full.

### Run simple animations off the main thread

Use [`useWaapiAnimate`](https://nanimejs.netlify.app/composables/use-waapi-animate) for `transform` and
`opacity` animations, such as modals, dropdowns and page entrances. The
browser runs them off the main thread, so they stay smooth during
hydration. It also adds less to the bundle: 5.5 KB with gzip, against
13.3 KB for `useAnimate`.

```vue [Modal.vue]
<script setup lang="ts">
const modal = useTemplateRef('modal')

useWaapiAnimate(modal, {
  transform: ['translateY(20px) scale(0.95)', 'translateY(0px) scale(1)'],
  opacity: [0, 1],
  duration: 300,
  ease: 'cubic-bezier(0.2, 0, 0, 1)',
})
</script>
```

Keep [`useAnimate`](https://nanimejs.netlify.app/composables/use-animate) for what the browser cannot
run on its own: SVG proxies (`morphTo`, `createMotionPath`,
`createDrawable`), text scrambling with `scrambleText` or
[`useScrambleText`](https://nanimejs.netlify.app/composables/use-scramble-text), and plain JavaScript
objects and numbers.

`useWaapiAnimate` follows [`reducedMotion`](https://nanimejs.netlify.app/guides/accessibility) too. It
cannot animate SVG proxies or plain objects.

### Use `useAnimatable` for constant values

For a value that changes many times a second, such as the cursor position,
[`useAnimatable`](https://nanimejs.netlify.app/composables/use-animatable) creates one animation up
front, and each call tweens from the current value:

```vue [Cursor.vue]
<script setup lang="ts">
const circle = useTemplateRef('circle')

const animatable = useAnimatable(circle, {
  translateX: 0,
  translateY: 0,
  ease: 'outExpo',
  duration: 300,
})

function onMouseMove(event: MouseEvent) {
  animatable.translateX(event.clientX)
  animatable.translateY(event.clientY)
}
</script>
```

### Split text by words or lines

[`useSplitText`](https://nanimejs.netlify.app/composables/use-split-text) wraps each piece in its own
element, so an article split into characters adds thousands of elements.
Split only headings and short callouts, and split by words or lines when
the effect allows it:

```vue [Heading.vue]
<script setup lang="ts">
import { stagger } from '#nanime/utils'

const heading = useTemplateRef('heading')
const { words } = useSplitText(heading, { words: true })

useAnimate(words, {
  translateY: [20, 0],
  opacity: [0, 1],
  delay: stagger(60),
  duration: 400,
})
</script>

<template>
  <h2 ref="heading">Ship it today</h2>
</template>
```

`stagger` is not auto-imported. The auto-imports cover the composables, so
import helpers such as `stagger` from `#nanime/utils`.

### Target elements with template refs

A selector such as `'.card'` matches every `.card` on the page. When the
component renders three times, each copy animates the cards of all the
others, so each card runs three animations. A template ref targets only
the component's own element:

```vue [Card.vue]
<script setup lang="ts">
const card = useTemplateRef('card')

useAnimate(card, { scale: [0.9, 1], opacity: [0, 1], duration: 400 })
</script>

<template>
  <div ref="card">Content</div>
</template>
```

### Animate transform and opacity

Animating `width`, `height` or `top` makes the browser recompute the layout
on every frame. Prefer `translateX`, `translateY`, `scale`, `rotate` and
`opacity`, which the browser only composites.
[Animations and performance](https://web.dev/articles/animations-and-performance)
explains the difference.

AnimeJS maps `x` and `y` to `transform`, so they are as cheap as
`translateX` and `translateY`.

## Check what each API adds to the bundle

`nanime` adds code only to the pages that call a composable or render a
component. The table lists what each one adds to the client bundle.

Sizes are what a page adds when it uses only that API, measured on
`nanime` 0.4.0 with AnimeJS 4.5.0 and Nuxt 4.5.2. Each number is the extra
client chunk size from `nuxt build`, minified with esbuild, with Vue and
Nuxt excluded.

<table>
<thead>
  <tr>
    <th align="left">
      Composable or component
    </th>
    
    <th align="left">
      Minified
    </th>
    
    <th align="left">
      Minified + gzip
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-split-text">
        <code>
          useSplitText
        </code>
      </a>
    </td>
    
    <td align="left">
      11.1 KB
    </td>
    
    <td align="left">
      4.2 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-waapi-animate">
        <code>
          useWaapiAnimate
        </code>
      </a>
    </td>
    
    <td align="left">
      13.9 KB
    </td>
    
    <td align="left">
      5.5 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-animatable">
        <code>
          useAnimatable
        </code>
      </a>
    </td>
    
    <td align="left">
      34.3 KB
    </td>
    
    <td align="left">
      13.1 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-animate">
        <code>
          useAnimate
        </code>
      </a>
    </td>
    
    <td align="left">
      35.0 KB
    </td>
    
    <td align="left">
      13.3 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/components/transition">
        <code>
          <AnimeTransition>
        </code>
      </a>
    </td>
    
    <td align="left">
      37.5 KB
    </td>
    
    <td align="left">
      14.5 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-scramble-text">
        <code>
          useScrambleText
        </code>
      </a>
    </td>
    
    <td align="left">
      37.8 KB
    </td>
    
    <td align="left">
      14.8 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-anime-timeline">
        <code>
          useAnimeTimeline
        </code>
      </a>
    </td>
    
    <td align="left">
      39.7 KB
    </td>
    
    <td align="left">
      15.0 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-anime-scroll">
        <code>
          useAnimeScroll
        </code>
      </a>
    </td>
    
    <td align="left">
      47.2 KB
    </td>
    
    <td align="left">
      17.5 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/composables/use-draggable">
        <code>
          useDraggable
        </code>
      </a>
    </td>
    
    <td align="left">
      58.8 KB
    </td>
    
    <td align="left">
      20.1 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/components/layout-group">
        <code>
          <AnimeLayoutGroup>
        </code>
      </a>
    </td>
    
    <td align="left">
      68.5 KB
    </td>
    
    <td align="left">
      23.8 KB
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <a href="https://nanimejs.netlify.app/components/transition-group">
        <code>
          <AnimeTransitionGroup>
        </code>
      </a>
    </td>
    
    <td align="left">
      75.1 KB
    </td>
    
    <td align="left">
      26.4 KB
    </td>
  </tr>
</tbody>
</table>

<note>

`useAnimate` and `useAnimeTimeline` on the same page add 40.8 KB
minified, not 74.7 KB (35.0 KB + 39.7 KB), because they share the AnimeJS
animation engine. `<AnimeTransition>` shares the same engine.

</note>

Imports from `#nanime/composables` add the same code as auto-imports.

A [preset](https://nanimejs.netlify.app/guides/presets) adds code only when you import it. The runtime
never imports the preset packages, so an app that sets no preset ships
none of them. A preset written in `app.config.ts` adds only the objects it
sets.


## Sitemap

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