Guides

Defaults

Set default props for the transition components and default parameters for useAnimate and useDraggable, for the whole app or part of it.

Set a default once instead of passing the same prop or parameter to every component and call. A prop or parameter you pass wins over provideAnimeDefaults(), which wins over app.config.ts, then the preset, then the built-in value.

Set app-wide defaults

app/app.config.ts
export default defineAppConfig({
  nanime: {
    components: {
      transition: { animation: 'slide-up', mode: 'out-in' },
      transitionGroup: { animation: 'swap', moveAnimation: { duration: 600, ease: 'out(4)' } },
      layoutGroup: { layoutOptions: { duration: 500 } },
    },
    composables: {
      animate: { duration: 500, ease: 'out(3)' },
      draggable: { releaseEase: 'out(3)', dragSpeed: 2 },
    },
  },
})

What can be a default

EntryProps that can be defaultsBuilt-in value when unset
components.transitionwaapi, animation, enterAnimation, leaveAnimation, mode, appear, completeOnTabHiddenfade (enter 300ms, leave 200ms), mode: 'default', appear: false
components.transitionGrouptag, waapi, animation, enterAnimation, leaveAnimation, moveAnimation, appear, absoluteLeave, shallow, completeOnTabHiddenenter 250ms with out(3), leave 150ms with in(3), move 350ms with out(3), tag: 'div', absoluteLeave: true
components.layoutGrouptag, shallow, layoutOptions, elements (selector string or list of strings), completeOnTabHiddenspring({ bounce: 0.15, duration: 300 }), tag: 'div'
composables.animateany AnimationParamsnone
composables.draggableany DraggableParams except trigger and containernone

deps cannot be a default, because every group watches different values. Element refs and component instances exist only inside a component, so they cannot be defaults either.

A composable parameter passed as undefined keeps the default, as it does in AnimeJS, so { duration: props.duration } works when the prop is not set.

Scope defaults to part of the app

Use provideAnimeDefaults() when one part of the app needs different defaults from the rest.

components/SettingsPanel.vue
<script setup lang="ts">
provideAnimeDefaults({
  transition: { animation: 'scale' },
  composables: { animate: { duration: 300 } },
  rebuild: 'keepTime',
})
</script>
KeyTypeNotes
transition, transitionGroup, layoutGroupsame as the components entriesReplaces the same entry from a parent component's call, so repeat any of the parent's keys you still need, such as mode.
composables{ animate?, draggable? }animate and draggable each replace the same entry from a parent component's call.
presetAnimationPresetReplaces the app-wide preset for the components and composables inside.
rebuild'restart', 'keepTime' or 'keepValue'Default rebuild for useAnimate, useScrambleText and useAnimeTimeline inside. 'keepValue' applies to useAnimate only, and the other two composables use 'restart' instead.

The argument can also be a ref or a getter. A key passed as undefined, such as transition: undefined, keeps the value from a parent component's call.

transitions and reducedMotion can only be set app-wide, so provideAnimeDefaults() does not accept them.

Copyright © 2026