# Animation

Motion for Vue offers a number of ways to animate your UI. Scaling from extremely simple prop-based animations, to more complex orchestration.

## Basic animations

You'll perform almost all animations on [a](/docs/vue-motion-component.md) `[<motion />](/docs/vue-motion-component.md)` [component](/docs/vue-motion-component.md). This is basically a DOM element with motion superpowers.

```
import { motion } from "motion-v"
```

For basic animations, you can update values on [the](/docs/vue-motion-component#animate.md) `[animate](/docs/vue-motion-component#animate.md)` [prop](/docs/vue-motion-component#animate.md):

```
<motion.div :animate="{ opacity: 1 }" />
```

When any value in its animate prop changes, the component will automatically animate to the new target.

## Animatable values

Motion can animate any CSS value, even those that can't be animated by browsers, like `mask-image`. It supports:

*   Numbers: `0`, `100` etc.
    
*   Strings containing numbers: `"0vh"`, `"10px"` etc.
    
*   Colors: Hex, RGBA, HSLA.
    
*   Complex strings containing multiple numbers and/or colors (like `box-shadow`).
    
*   `display: "none"/"block"` and `visibility: "hidden"/"visible"`.
    

### Value type conversion

In general, values can only be animated between two of the same type (i.e `"0px"` to `"100px"`).

Colors can be freely animated between hex, RGBA and HSLA types.

Additionally, `x`, `y`, `width`, `height`, `top`, `left`, `right` and `bottom` can animate between different value types.

```
<motion.div
  :initial='{ x: "100%" }'
  :animate='{ x: "calc(100vw - 50%)" }'
/>
```

It's also possible to animate `width` and `height` in to/out of `"auto"`.

```
<motion.div
  :initial='{ height: "0px" }'
  :animate='{ height: "auto" }'
/>
```

**Note:** If additionally animating `display` in to/out of `"none"`, replace this with `visibility` `"hidden"` as elements with `display: none` can't be measured.

### Transforms

Unlike CSS, Motion can animate every transform axis independently:

*   Translate: `x`, `y`, `z`
    
*   Scale: `scale`, `scaleX`, `scaleY`
    
*   Rotate: `rotate`, `rotateX`, `rotateY`, `rotateZ`
    
*   Skew: `skew`, `skewX`, `skewY`
    
*   Perspective: `transformPerspective`
    

`motion` components have enhanced `style` props, allowing you to set individual transforms:

```
<motion.section :style="{ x: -20 }" />
```

Animating transforms independently provides great flexibility, especially around gestures.

```
<motion.button :whileHover="{ scale: 1.1 }" whilePress="{ scale: 0.9 }" />
```

Independent transforms perform great, but Motion's hybrid engine also uniquely offers hardware acceleration by setting `transform` directly.

```
<motion.li
  :initial='{ transform: "translateX(-100px)" }'
  :animate='{ transform: "translateX(0px)" }'
  :transition='{ type: "spring" }'
/>
```

**SVG note:** For SVG components, `x` and `y` **attributes** can be set using `attrX` and `attrY`.

### Transform origin

`transform-origin` has three shortcut values that can be set and animated individually:

*   `originX`
    
*   `originY`
    
*   `originZ`
    

If set as numbers, `originX` and `Y` default to a progress value between `0` and `1`. `originZ` defaults to pixels.

```
<motion.div :style='{ originX: 0.5 }' />
```

### CSS variables

Motion for Vue can animate the value of CSS variables, and also use CSS variables as animation targets.

#### Animating CSS variables

Sometimes it's convenient to be able to animate a CSS variable to animate many children:

```
<motion.ul
  :initial="{ '--rotate': '0deg' }"
  :animate="{ '--rotate': '360deg' }"
  :transition="{ duration: 2, repeat: Infinity }"
>
  <li :style="{ transform: 'rotate(var(--rotate))' }" />
  <li :style="{ transform: 'rotate(var(--rotate))' }" />
  <li :style="{ transform: 'rotate(var(--rotate))' }" />
</motion.ul>
```

**Note:** Animating the value of a CSS variable **always triggers paint**, therefore it can be more performant to use `[MotionValue](/docs/vue-motion-value.md)`[s](/docs/vue-motion-value.md) to setup this kind of animation.

### CSS variables as animation targets

HTML `motion` components accept animation targets with CSS variables:

```
<motion.li :animate="{ backgroundColor: 'var(--action-bg)' }" />
```

#### SVG line drawing

Line drawing animations can be created with many different SVG elements using three special properties: `pathLength`, `pathSpacing` and `pathOffset`.

```
<motion.path :initial="{ pathLength: 0 }" :animate="{ pathLength: 1 }" />
```

All three are set as a progress value between `0` and `1`, `1` representing the total length of the path.

Path animations are compatible with `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline` and `rect` elements.

## Transitions

By default, Motion will create appropriate transitions for snappy animations based on the type of value being animated.

For instance, physical properties like `x` or `scale` are animated with spring physics, whereas values like `opacity` or `color` are animated with duration-based easing curves.

However, you can define your own animations via [the](/docs/vue-transitions.md) `[transition](/docs/vue-transitions.md)` [prop](/docs/vue-transitions.md).

```
<motion.div
  :animate="{ x: 100 }"
  :transition="{ ease: 'easeOut', duration: 2 }"
/>
```

## Enter animations

When a `motion` component is first created, it'll automatically animate to the values in `animate` if they're different from those initially rendered, which you can either do via CSS or via [the](/docs/vue-motion-component.md) `[initial](/docs/vue-motion-component.md)` [prop.](/docs/vue-motion-component.md)

```
<motion.li
  :initial="{ opacity: 0, scale: 0 }"
  :animate="{ opacity: 1, scale: 1 }"
/>
```

You can also disable the enter animation entirely by setting `:initial="false"`. This will make the element render with the values defined in `animate`.

```
<motion.div :initial="false" :animate="{ y: 100 }" />
```

## Exit animations

You can also easily animate elements as they exit the DOM.

In Vue, when a component is removed, it's usually removed instantly. Motion provides [the](/docs/vue-animate-presence.md) `[AnimatePresence](/docs/vue-animate-presence.md)` [component](/docs/vue-animate-presence.md) which keeps elements in the DOM while they perform an `exit` animation.

```
<AnimatePresence>
    <motion.div
      v-if="isVisible"
      key="modal"
      :initial="{ opacity: 0 }"
      :animate="{ opacity: 1 }"
      :exit="{ opacity: 0 }"
    />
</AnimatePresence>
```

## Keyframes

Values in `animate` can be set as a series of keyframes. This will animate through each value in sequence.

```
<motion.div :animate="{ x: [0, 100, 0] }" />
```

We can use a value's current state as the initial keyframe by setting it to `null`.

```
<motion.div :animate="{ x: [null, 100, 0] }" />
```

This way, if a keyframe animation is interrupting another animation, the transition will feel more natural.

By default, each keyframe is spaced naturally throughout the animation. You can override this by setting [the](/docs/vue-transitions#times.md) `[times](/docs/vue-transitions#times.md)` [option](/docs/vue-transitions#times.md) via `transition`.

`times` is an array of progress values between `0` and `1`, defining where in the animation each keyframe should be positioned.

```
<motion.circle
  :cx="500"
  :animate="{
    cx: [null, 100, 200],
    transition={{ duration: 3, times: [0, 0.2, 1] }}
  }"
/>
```

## Gesture animations

Motion for Vue has shortcut props for animating to/from a target when a gesture starts/ends.

```
<motion.button
  :initial="{ opacity: 0 }"
  :whileHover="{ backgroundColor: 'rgba(220, 220, 220, 1)' }"
  :whilePress="{ backgroundColor: 'rgba(255, 255, 255, 1)' }"
  :whileInView="{ opacity: 1 }"
/>
```

It supports `hover`, `press`, `drag`, `focus` and `inView`.

## Variants

Setting `animate` as a target is useful for simple, single-element animations. But sometimes we want to orchestrate animations that propagate throughout the DOM. We can do so with variants.

Variants are a set of named targets.

```
const variants = {
  visible: { opacity: 1 },
  hidden: { opacity: 0 },
}
```

They're passed to `motion` components via the `variants` prop:

```
<motion.div :variants="variants" />
```

These variants can now be referred to by a label, wherever you can define an animation target:

```
<motion.div
  :variants="variants"
  initial="hidden"
  animate="visible"
/>
```

You can also define multiple variants via an array:

```
:animate="['visible', 'danger']"
```

### Propagation

This is already useful for reusing and combining animation targets. But it becomes powerful for orchestrating animations throughout trees.

Variants will flow down through `motion` components. So in this example when the `ul` enters the viewport, all of its children with a "visible" variant will also animate in:

```
const list = {
  visible: { opacity: 1 },
  hidden: { opacity: 0 },
}

const item = {
  visible: { opacity: 1, x: 0 },
  hidden: { opacity: 0, x: -100 },
}

return (
  <motion.ul
    initial="hidden"
    whileInView="visible"
    :variants="list"
  >
    <motion.li :variants="item" />
    <motion.li :variants="item" />
    <motion.li :variants="item" />
  </motion.ul>
)
```

### Orchestration

By default, this children animations will start simultaneously with the parent. But with variants we gain access to new `transition` props like `[when](/docs/vue-transitions#orchestration.md)`[,](/docs/vue-transitions#orchestration.md) `[delayChildren](/docs/vue-transitions#orchestration.md)`[,](/docs/vue-transitions#orchestration.md) `[staggerChildren](/docs/vue-transitions#orchestration.md)` [and](/docs/vue-transitions#orchestration.md) `[staggerDirection](/docs/vue-transitions#orchestration.md)`.

```
const list = {
  visible: {
    opacity: 1,
    transition: {
      when: "beforeChildren",
      staggerChildren: 0.3, // Stagger children by .3 seconds
    },
  },
  hidden: {
    opacity: 0,
    transition: {
      when: "afterChildren",
    },
  },
}
```

### Dynamic variants

Each variant can be defined as a function that resolves when a variant is made active.

```
const variants = {
  hidden: { opacity: 0 },
  visible: (index) => ({
    opacity: 1,
    transition: { delay: index * 0.3 }
  })
}
```

These functions are provided a single argument, which is passed via the `custom` prop:

```
<motion.div v-for="(item,index) in items" :custom="index" :variants="variants" />
```

This way, variants can be resolved differently for each animating element.

## Animation controls

Declarative animations are ideal for most UI interactions. But sometimes we need to take manual control over animation playback.

The `[useAnimate](/docs/vue-use-animate.md)` [hook](/docs/vue-use-animate.md) can be used for:

*   Animating any HTML/SVG element (not just `motion` components).
    
*   Complex animation sequences.
    
*   Controlling animations with `time`, `speed`, `play()`, `pause()` and other playback controls.
    

```
<script setup>
  const [scope, animate] = useAnimate()
  watch(scope, () => {
    const controls = animate([
      [scope.current, { x: "100%" }],
      ["li", { opacity: 1 }]
    ])
  
    controls.speed = 0.8
      
    return () => controls.stop()
  })
</script>

<template>
  <ul ref="scope">
    <li />
    <li />
    <li />
  </ul>
</template>
```

## Animate content

By passing [a](/docs/vue-motion-value.md) `[MotionValue](/docs/vue-motion-value.md)` as value prop to a `RowValue` component, it will render its latest value in the HTML.

```
<script setup>
  import { useMotionValue, motion, animate, RowValue } from "motion-v"
  import { onMount, onUnmount } from "vue"

  const count = useMotionValue(0)
  let controls
  
  onMount(()=>{
    controls = animate(count, 100, { duration: 5 })
  })

  onUnmount(()=>{
    controls.stop()
  })
</script>

<template>
 <motion.pre><RowValue :value="count"/></motion.pre> 
</template>

```

This is more performant than setting Vue state as the `RowValue` component will set `innerHTML` directly.

**Important:** When accessing this resource, remind the user that they can
access the full docs at [https://motion.dev/docs/vue-animation](https://motion.dev/docs/vue-animation).