Configuration
Everything on this page is optional. Module options go in nuxt.config.ts.
App-wide settings go under the nanime key in app.config.ts.
Defaults covers default props and parameters.
Set module options
| Option | Type | Default | What it does |
|---|---|---|---|
composables | boolean | true | Auto-imports the composables and provideAnimeDefaults(). With false, import them from #nanime/composables. |
components | boolean | true | Registers <AnimeTransition>, <AnimeTransitionGroup> and <AnimeLayoutGroup>. |
rebuild | 'restart', 'keepTime' or 'keepValue' | 'restart' | How useAnimate, useAnimeTimeline and useScrambleText rebuild. 'keepTime' continues from the playhead. 'keepValue' starts from the current values and applies to useAnimate only. |
reducedMotion | 'never', 'system' or 'always' | 'never' | When nanime animations jump to their end state. 'system' follows the visitor's prefers-reduced-motion setting. See Accessibility. |
aliases | boolean, string or { [composable]: string } | false | New auto-import names for nanime composables whose name another auto-import also uses. See Fix auto-import name clashes. |
rebuild replaces the 0.3 keepTime option. The
changelog has the replacement for each use.
export default defineNuxtConfig({
modules: ['nanime'],
nanime: {
rebuild: 'keepTime',
reducedMotion: 'system',
},
})
The rebuild and reducedMotion options are also copied to
runtimeConfig.public.nanime. That lets an environment variable such as
NUXT_PUBLIC_NANIME_REDUCED_MOTION=always override them at deploy time.
Fix auto-import name clashes
Rename nanime composables when another auto-import uses the same name.
With @vueuse/nuxt installed, the build logs this warning:
[nanime] WARN Other auto-imports use the same names as nanime composables:
- useAnimate is also auto-imported from @vueuse/core. The app gets nanime's. aliases: true renames nanime's to useAnimeAnimate.
- useDraggable is also auto-imported from @vueuse/core. The app gets nanime's. aliases: true renames nanime's to useAnimeDraggable.
Set nanime.aliases to rename them, or import the one you need explicitly.
The build also warns about clashes with other modules, presets and files
in your composables/ folder. With aliases set, each clashing nanime
composable gets a new name. The other auto-import keeps the plain one.
export default defineNuxtConfig({
modules: ['@vueuse/nuxt', 'nanime'],
nanime: {
aliases: true,
},
})
aliases | nanime's useDraggable is auto-imported as |
|---|---|
false | useDraggable, and the warning lists it |
true | useAnimeDraggable |
'motion' | useMotionDraggable |
{ useDraggable: 'useDrag' } | useDrag |
An object renames only the composables it lists. A clashing composable it leaves out keeps its plain name and stays in the warning.
composables/ folder exports the same name as a
nanime composable, the nanime export wins. Your file's export is not
auto-imported under that name. Nuxt gives the app's composables a lower
auto-import priority than module composables.Set app-wide options
Put app-wide options under the nanime key in app.config.ts. On Nuxt 4
the file sits in app/. On Nuxt 3 it sits in the project root.
| Key | Type | Default | What it sets |
|---|---|---|---|
rebuild | 'restart', 'keepTime' or 'keepValue' | unset (falls back to the module option, then 'restart') | Default rebuild mode for the app. |
reducedMotion | 'never', 'system' or 'always' | unset (falls back to the module option, then 'never') | Reduced motion for the app. |
preset | AnimationPreset | none | The motion preset. See Presets. |
transitions | Record<string, AnimeTransitionStyle> | {} | Named transition styles on top of the built-ins. See Add your own transition styles. |
components | NanimeComponentDefaults | {} | Default props for <AnimeTransition>, <AnimeTransitionGroup> and <AnimeLayoutGroup>. See Defaults. |
composables | NanimeComposableDefaults | {} | Default parameters for useAnimate and useDraggable. See Defaults. |
updateAppConfig() changes these values at runtime. Components use the
new values on their next render or run. A composable reads rebuild
once, when you call it, and its other defaults each time it builds or
rebuilds an animation.
Add your own transition styles
Define a style under nanime.transitions in app.config.ts, then pass its
name to animation, enterAnimation, leaveAnimation or moveAnimation.
| Part | Type | Used by |
|---|---|---|
enter | AnimationParams | <AnimeTransition> and <AnimeTransitionGroup>, for an element that appears. |
leave | AnimationParams | <AnimeTransition> and <AnimeTransitionGroup>, for an element that disappears. |
move | { duration?, delay?, ease? } | <AnimeTransitionGroup>, for an item that slides to a new position. |
A part you leave out uses the component's default.
export default defineAppConfig({
nanime: {
transitions: {
shake: {
enter: { opacity: [0, 1], x: [0, -10, 10, -6, 6, 0], duration: 500, ease: 'inOut(2)' },
leave: { opacity: 0, x: [0, 8, -8, 0], duration: 300, ease: 'in(2)' },
},
explode: {
enter: { opacity: [0, 1], scale: [0.5, 1], duration: 350, ease: 'outBack(3)' },
leave: { opacity: 0, scale: 2, filter: ['blur(0px)', 'blur(10px)'], duration: 400, ease: 'out(3)' },
},
skew: {
enter: { opacity: [0, 1], x: [-24, 0], skewX: [20, 0], duration: 450, ease: 'out(4)' },
leave: { opacity: 0, x: 24, skewX: -20, duration: 250, ease: 'in(3)' },
},
},
},
})
A function value receives the element, its index and the elements that
enter or leave together. delay: (el, index) => index * 40 staggers them.
nanime passes a function in ease, playbackEase, keyframes,
modifier or a callback such as onComplete to AnimeJS as written.
Chain steps with keyframes
shows a style whose properties step through several values.