AutoAnimate

Install AutoAnimate using your preferred package manager to add smooth transitions to your web application.

# yarn
yarn add @formkit/auto-animate

# npm
npm install @formkit/auto-animate

# pnpm
pnpm add @formkit/auto-animate

Instead of standard options, you can pass a function as the configuration to create a custom plugin. This allows you to define custom KeyframeEffects for different DOM actions: add, remove, or remain (moving).

A plugin can return either a single KeyframeEffect or a tuple containing [KeyframeEffect, AutoAnimationPluginOptions] to provide custom CSS styles during the animation.

import autoAnimate, { AutoAnimationPlugin, AutoAnimationPluginOptions } from '@formkit/auto-animate'

const myPlugin: AutoAnimationPlugin = (el, action, newCoords, oldCoords) => {
  if (action === 'add') {
    return [
      el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 500 })[0],
      { styleReset: { color: 'red' } } // Custom styles during animation
    ]
  }
  // ... handle 'remove' and 'remain'
  return []
}

autoAnimate(el, myPlugin)

You can install AutoAnimate as a Vue plugin to make the v-auto-animate directive available globally throughout your application. You can optionally provide global default options or a plugin during installation.

import { autoAnimatePlugin } from '@formkit/auto-animate/vue'

// Basic installation
app.use(autoAnimatePlugin)

// Installation with global default options
app.use(autoAnimatePlugin, { duration: 300 })

You can pass a configuration object to autoAnimate to customize the transition behavior. These options apply to all elements within the observed tree.

const config: Partial<AutoAnimateOptions> = {
  duration: 250,           // Transition duration in milliseconds
  easing: 'ease-in-out',   // 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | string
  disrespectUserMotionPreference: false // If true, ignores 'prefers-reduced-motion' settings
}

To add automatic animations to an Angular application, use the AutoAnimateDirective. This directive can be applied to any element using the [auto-animate] selector. It is a standalone directive that accepts an options input, allowing you to pass configuration compatible with AutoAnimateOptions.

Because it uses an Angular effect, the animation logic will automatically re-initialize whenever the options input changes.

import { AutoAnimateDirective } from './path-to-angular-package';

// In your component template:
// <div [auto-animate]="{ duration: 300 }">
//   <!-- Elements changing inside here will animate -->
// </div>

For Vue applications, use the vAutoAnimate directive to easily attach animation logic to an element via the template.

<template>
  <!-- Basic usage -->
  <div v-auto-animate>
    <div v-for="item in items" :key="item.id">{{ item.text }}</div>
  </div>

  <!-- With custom options -->
  <div v-auto-animate="{ duration: 500 }">
    ... 
  </div>
</template>

The useAutoAnimate hook is a generic function designed for Preact elements.

Signature: useAutoAnimate<T extends Element>(options?: Partial<AutoAnimateOptions> | AutoAnimationPlugin): [Object<T>, (enabled: boolean) => void]

Parameters:

• options: An optional configuration object of type Partial<AutoAnimateOptions> or an AutoAnimationPlugin.

Returns: A tuple containing:

1. element: A ref (Object) of type T to be attached to the target DOM element.
2. setEnabled: A function (enabled: boolean) => void used to enable or disable the animation controller.

Use the autoAnimate function to add automatic animations to a parent element and its children. It monitors DOM mutations (adding, removing, or moving elements) and applies smooth transitions.

By default, it respects the user's prefers-reduced-motion setting. If the browser is not supported or motion is reduced, animations will be disabled unless disrespectUserMotionPreference: true is passed in the config.

import autoAnimate from '@formkit/auto-animate'

const parent = document.querySelector('.parent')
const controls = autoAnimate(parent, { duration: 300, easing: 'ease-in-out' })
// 'controls' can be used to enable/disable animations later

The v-auto-animate directive can be applied to an HTML element or a Vue component to automatically animate changes to its children (e.g., additions, removals, or reordering).

If you installed the plugin via app.use(autoAnimatePlugin), you can use the directive directly in your templates. You can pass AutoAnimateOptions or an AutoAnimationPlugin as the directive value.

<!-- Basic usage -->
<ul v-auto-animate>
  <li v-for="item in items" :key="item.id">{{ item.text }}</li>
</ul>

<!-- Usage with specific options -->
<ul v-auto-animate="{ duration: 500 }">
  <li v-for="item in items" :key="item.id">{{ item.text }}</li>
</ul>

The useAutoAnimate composable provides a more programmatic way to apply animations using a template ref. It returns a tuple containing:

1. A Ref to the element (or component) to be animated.
2. A setEnabled function to enable or disable animations dynamically.

This is useful when you need fine-grained control over when animations are active or when working with complex component lifecycles.

import { useAutoAnimate } from '@formkit/auto-animate/vue'

export default {
  setup() {
    const [animate] = useAutoAnimate({ duration: 300 })

    const toggleAnimations = (enabled: boolean) => {
      animate(enabled)
    }

    return {
      animate,
      toggleAnimations
    }
  }
}

<template>
  <ul ref="animate">
    <li v-for="item in items" :key="item.id">{{ item.text }}</li>
  </ul>
</template>