Configuration

Everything on this page is optional. The module options go in nuxt.config.ts. Transition styles and component defaults go in app.config.ts.

Set module options

export default defineNuxtConfig({
  modules: ['nanime'],
  nanime: {}
})

composables

• Type: boolean
• Default: true

Auto-imports the composables and provideAnimeDefaults(). Set it to false to import them from #nanime/composables instead:

nanime: {
  composables: false
}

import { useAnimate } from '#nanime/composables'

components

• Type: boolean
• Default: true

Registers <AnimeTransition>, <AnimeTransitionGroup> and <AnimeLayoutGroup>, and adds the stylesheet they use. Set it to false to leave the components and the stylesheet out of the app:

nanime: {
  components: false
}

keepTime

• Type: boolean
• Default: false

Sets the default keepTime for useAnimate, useAnimeTimeline and useScrambleText, the composables that accept it. With true, an animation rebuilt by a reactive change continues from where it was instead of restarting. A keepTime passed to one composable call overrides the module default:

nanime: {
  keepTime: true
}

// restarts on rebuild even though the module default is true
useAnimate(target, { x: 100 }, { keepTime: false })

reducedMotion

• Type: 'never' | 'system' | 'always'
• Default: 'never'

Makes nanime animations and transitions jump to their end state instead of playing. 'system' follows the visitor's prefers-reduced-motion setting. reducedMotion in app.config.ts overrides this option. Accessibility lists what it affects and shows a runtime toggle.

nanime: {
  reducedMotion: 'system'
}

Add transition styles

Custom transition styles go under nanime.transitions in app.config.ts. Unlike nuxt.config.ts, app.config.ts is bundled into the client, so a style can hold a function, such as delay: () => Math.random() * 200.

export default defineAppConfig({
  nanime: {
    transitions: {
      pop: {
        enter: { opacity: [0, 1], scale: [0.4, 1], duration: 700 },
        leave: { opacity: 0, scale: 0.4, duration: 250 },
      },
    },
  },
})

Each style can set enter, leave and move. Pass its name to a component, as in <AnimeTransition enter-animation="pop">. A style with a built-in name, such as fade, replaces the built-in.

Set component defaults

Default props for each component go under nanime.components. The keys are transition for <AnimeTransition>, transitionGroup for <AnimeTransitionGroup> and layoutGroup for <AnimeLayoutGroup>. A prop passed to the component wins over its default.

export default defineAppConfig({
  nanime: {
    components: {
      transition: { enterAnimation: 'slide-up', mode: 'out-in' },
      transitionGroup: { moveAnimation: { duration: 600, ease: 'out(4)' } },
      layoutGroup: { layoutOptions: { duration: 500 } },
    },
  },
})

Set defaults for part of the app

provideAnimeDefaults() sets component defaults for everything rendered below the component that calls it. It takes the same shape as nanime.components, or a getter that returns one.

<script setup lang="ts">
provideAnimeDefaults({
  transition: { enterAnimation: 'scale' },
})
</script>

Defaults merge per prop, from lowest to highest priority:

1. The built-in default.
2. nanime.components in app.config.ts.
3. Each provideAnimeDefaults() call, outermost first.
4. The prop passed to the component.

A default set to undefined is skipped, and the one below it applies. A getter can return undefined for a prop to fall back that way.

An object default, such as enterAnimation: { duration: 400 }, replaces the one below it whole. layoutOptions on the layout group is the one exception. Its keys merge, so duration from app.config.ts and ease from a provider both apply.