1---
2category: Animation
3---
4 
5# useAnimate
6 
7Reactive [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
8 
9## Usage
10 
11### Basic Usage
12 
13The `useAnimate` function returns the animation instance and control functions.
14 
15```vue
16<script setup lang="ts">
17import { useAnimate } from '@vueuse/core'
18import { useTemplateRef } from 'vue'
19 
20const el = useTemplateRef('el')
21const {
22  isSupported,
23  animate,
24 
25  // actions
26  play,
27  pause,
28  reverse,
29  finish,
30  cancel,
31 
32  // states
33  pending,
34  playState,
35  replaceState,
36  startTime,
37  currentTime,
38  timeline,
39  playbackRate,
40} = useAnimate(el, { transform: 'rotate(360deg)' }, 1000)
41</script>
42 
43<template>
44  <span ref="el" style="display:inline-block">useAnimate</span>
45</template>
46```
47 
48### Custom Keyframes
49 
50Either an array of keyframe objects, or a keyframe object, or a `ref`. See [Keyframe Formats](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) for more details.
51 
52```ts
53import { useAnimate } from '@vueuse/core'
54import { useTemplateRef } from 'vue'
55 
56const el = useTemplateRef('el')
57// ---cut---
58const keyframes = { transform: 'rotate(360deg)' }
59// Or
60const keyframes = [
61  { transform: 'rotate(0deg)' },
62  { transform: 'rotate(360deg)' },
63]
64// Or
65const keyframes = ref([
66  { clipPath: 'circle(20% at 0% 30%)' },
67  { clipPath: 'circle(20% at 50% 80%)' },
68  { clipPath: 'circle(20% at 100% 30%)' },
69])
70 
71useAnimate(el, keyframes, 1000)
72```
73 
74### Options
75 
76The third argument accepts a duration number or an options object with the following additional properties on top of [KeyframeAnimationOptions](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate#parameters):
77 
78```ts
79import { useAnimate } from '@vueuse/core'
80 
81useAnimate(el, keyframes, {
82  duration: 1000,
83  // Start playing immediately (default: true)
84  immediate: true,
85  // Commit the end styling state to the element (default: false)
86  commitStyles: false,
87  // Persist the animation (default: false)
88  persist: false,
89  // Callback when animation is initialized
90  onReady(animate) {
91    console.log('Animation ready', animate)
92  },
93  // Callback when an error occurs
94  onError(e) {
95    console.error('Animation error', e)
96  },
97})
98```
99 
100### Delaying Start
101 
102Set `immediate: false` to prevent the animation from starting automatically.
103 
104```ts
105import { useAnimate } from '@vueuse/core'
106 
107const { play } = useAnimate(el, keyframes, {
108  duration: 1000,
109  immediate: false,
110})
111 
112// Start the animation manually
113play()
114```
115 
116## Type Declarations
117 
118```ts
119export interface UseAnimateOptions
120  extends KeyframeAnimationOptions, ConfigurableWindow {
121  /**
122   * Will automatically run play when `useAnimate` is used
123   *
124   * @default true
125   */
126  immediate?: boolean
127  /**
128   * Whether to commits the end styling state of an animation to the element being animated
129   * In general, you should use `fill` option with this.
130   *
131   * @default false
132   */
133  commitStyles?: boolean
134  /**
135   * Whether to persists the animation
136   *
137   * @default false
138   */
139  persist?: boolean
140  /**
141   * Executed after animation initialization
142   */
143  onReady?: (animate: Animation) => void
144  /**
145   * Callback when error is caught.
146   */
147  onError?: (e: unknown) => void
148}
149export type UseAnimateKeyframes = MaybeRef<
150  Keyframe[] | PropertyIndexedKeyframes | null
151>
152export interface UseAnimateReturn extends Supportable {
153  animate: ShallowRef<Animation | undefined>
154  play: () => void
155  pause: () => void
156  reverse: () => void
157  finish: () => void
158  cancel: () => void
159  pending: ComputedRef<boolean>
160  playState: ComputedRef<AnimationPlayState>
161  replaceState: ComputedRef<AnimationReplaceState>
162  startTime: WritableComputedRef<CSSNumberish | number | null>
163  currentTime: WritableComputedRef<CSSNumberish | null>
164  timeline: WritableComputedRef<AnimationTimeline | null>
165  playbackRate: WritableComputedRef<number>
166}
167/**
168 * Reactive Web Animations API
169 *
170 * @see https://vueuse.org/useAnimate
171 * @param target
172 * @param keyframes
173 * @param options
174 */
175export declare function useAnimate(
176  target: MaybeComputedElementRef,
177  keyframes: UseAnimateKeyframes,
178  options?: number | UseAnimateOptions,
179): UseAnimateReturn
180```
181