Guides

Performance

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

Each tip makes nanime do less work.

TipApplies toWhat to do
Group deps<AnimeTransitionGroup>, <AnimeLayoutGroup>Pass deps so a group measures only when its state changes.
Group size<AnimeTransitionGroup>, <AnimeLayoutGroup>Keep the part that moves small.
WAAPIuseWaapiAnimateUse it for transform and opacity animations.
Constant valuesuseAnimatableTween from the current value instead of restarting an animation.
TextuseSplitTextSplit headings by words or lines, not characters.
TargetsEvery composablePass a template ref, not a selector string.
PropertiesEvery composableAnimate transform and opacity, not layout properties.
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 covers the prop.

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.

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:

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:

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:

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

Choose which elements animate covers elements in full.

Run simple animations off the main thread

Use useWaapiAnimate 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.

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 for what the browser cannot run on its own: SVG proxies (morphTo, createMotionPath, createDrawable), text scrambling with scrambleText or useScrambleText, and plain JavaScript objects and numbers.

useWaapiAnimate follows reducedMotion 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 creates one animation up front, and each call tweens from the current value:

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

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:

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

Composable or componentMinifiedMinified + gzip
useSplitText11.1 KB4.2 KB
useWaapiAnimate13.9 KB5.5 KB
useAnimatable34.3 KB13.1 KB
useAnimate35.0 KB13.3 KB
<AnimeTransition>37.5 KB14.5 KB
useScrambleText37.8 KB14.8 KB
useAnimeTimeline39.7 KB15.0 KB
useAnimeScroll47.2 KB17.5 KB
useDraggable58.8 KB20.1 KB
<AnimeLayoutGroup>68.5 KB23.8 KB
<AnimeTransitionGroup>75.1 KB26.4 KB
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.

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

A preset 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.

Copyright © 2026