Guides

Configuration

The module options and the app-wide settings.

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

OptionTypeDefaultWhat it does
composablesbooleantrueAuto-imports the composables and provideAnimeDefaults(). With false, import them from #nanime/composables.
componentsbooleantrueRegisters <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.
aliasesboolean, string or { [composable]: string }falseNew 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.

nuxt.config.ts
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.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt', 'nanime'],
  nanime: {
    aliases: true,
  },
})
aliasesnanime's useDraggable is auto-imported as
falseuseDraggable, and the warning lists it
trueuseAnimeDraggable
'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.

When a file in your 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.

KeyTypeDefaultWhat 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.
presetAnimationPresetnoneThe motion preset. See Presets.
transitionsRecord<string, AnimeTransitionStyle>{}Named transition styles on top of the built-ins. See Add your own transition styles.
componentsNanimeComponentDefaults{}Default props for <AnimeTransition>, <AnimeTransitionGroup> and <AnimeLayoutGroup>. See Defaults.
composablesNanimeComposableDefaults{}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.

PartTypeUsed by
enterAnimationParams<AnimeTransition> and <AnimeTransitionGroup>, for an element that appears.
leaveAnimationParams<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.

View on GitHub
app/app.config.ts
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.

Copyright © 2026