Performance
Each tip makes nanime do less work.
| Tip | Applies to | What 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. |
| WAAPI | useWaapiAnimate | Use it for transform and opacity animations. |
| Constant values | useAnimatable | Tween from the current value instead of restarting an animation. |
| Text | useSplitText | Split headings by words or lines, not characters. |
| Targets | Every composable | Pass a template ref, not a selector string. |
| Properties | Every composable | Animate transform and opacity, not layout properties. |
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.
<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:
<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:
<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:
<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.
<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:
<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:
<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:
<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 component | Minified | Minified + gzip |
|---|---|---|
useSplitText | 11.1 KB | 4.2 KB |
useWaapiAnimate | 13.9 KB | 5.5 KB |
useAnimatable | 34.3 KB | 13.1 KB |
useAnimate | 35.0 KB | 13.3 KB |
<AnimeTransition> | 37.5 KB | 14.5 KB |
useScrambleText | 37.8 KB | 14.8 KB |
useAnimeTimeline | 39.7 KB | 15.0 KB |
useAnimeScroll | 47.2 KB | 17.5 KB |
useDraggable | 58.8 KB | 20.1 KB |
<AnimeLayoutGroup> | 68.5 KB | 23.8 KB |
<AnimeTransitionGroup> | 75.1 KB | 26.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.