---
category: Animation
---

# useAnimate

Reactive [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).

## Usage

### Basic Usage

The `useAnimate` function will return the animate and its control function.

```vue
<script setup lang="ts">
import { useAnimate } from '@vueuse/core';
import { useTemplateRef } from 'vue';

const el = useTemplateRef('el');
const {
  isSupported,
  animate,

  // actions
  play,
  pause,
  reverse,
  finish,
  cancel,

  // states
  pending,
  playState,
  replaceState,
  startTime,
  currentTime,
  timeline,
  playbackRate,
} = useAnimate(el, { transform: 'rotate(360deg)' }, 1000);
</script>

<template>
  <span ref="el" style="display:inline-block">useAnimate</span>
</template>
```

### Custom Keyframes

Either 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.

```ts
import { useAnimate } from '@vueuse/core';
import { useTemplateRef } from 'vue';

const el = useTemplateRef('el');
// ---cut---
const keyframes = { transform: 'rotate(360deg)' };
// Or
const keyframes = [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }];
// Or
const keyframes = ref([
  { clipPath: 'circle(20% at 0% 30%)' },
  { clipPath: 'circle(20% at 50% 80%)' },
  { clipPath: 'circle(20% at 100% 30%)' },
]);

useAnimate(el, keyframes, 1000);
```

## Type Declarations

```ts
export interface UseAnimateOptions extends KeyframeAnimationOptions, ConfigurableWindow {
  /**
   * Will automatically run play when `useAnimate` is used
   *
   * @default true
   */
  immediate?: boolean;
  /**
   * Whether to commits the end styling state of an animation to the element being animated
   * In general, you should use `fill` option with this.
   *
   * @default false
   */
  commitStyles?: boolean;
  /**
   * Whether to persists the animation
   *
   * @default false
   */
  persist?: boolean;
  /**
   * Executed after animation initialization
   */
  onReady?: (animate: Animation) => void;
  /**
   * Callback when error is caught.
   */
  onError?: (e: unknown) => void;
}
export type UseAnimateKeyframes = MaybeRef<Keyframe[] | PropertyIndexedKeyframes | null>;
export interface UseAnimateReturn {
  isSupported: ComputedRef<boolean>;
  animate: ShallowRef<Animation | undefined>;
  play: () => void;
  pause: () => void;
  reverse: () => void;
  finish: () => void;
  cancel: () => void;
  pending: ComputedRef<boolean>;
  playState: ComputedRef<AnimationPlayState>;
  replaceState: ComputedRef<AnimationReplaceState>;
  startTime: WritableComputedRef<CSSNumberish | number | null>;
  currentTime: WritableComputedRef<CSSNumberish | null>;
  timeline: WritableComputedRef<AnimationTimeline | null>;
  playbackRate: WritableComputedRef<number>;
}
/**
 * Reactive Web Animations API
 *
 * @see https://vueuse.org/useAnimate
 * @param target
 * @param keyframes
 * @param options
 */
export declare function useAnimate(
  target: MaybeComputedElementRef,
  keyframes: UseAnimateKeyframes,
  options?: number | UseAnimateOptions,
): UseAnimateReturn;
```