# formkit/auto-animate: one line of code for list transitions

> AutoAnimate is a zero-config drop-in utility that animates DOM changes in Vue, React, Solid, Preact and Marko. It is small, MIT-licensed, and deliberately not a full animation library.

**formkit/auto-animate** — A zero-config, drop-in animation utility that adds smooth transitions to your web app. You can use it with React, Vue, or any other JavaScript application.

- Repository: https://github.com/formkit/auto-animate
- Website: https://auto-animate.formkit.com
- Stars: 13,926 · Forks: 260
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/formkit-auto-animate

## What AutoAnimate actually animates

AutoAnimate targets a narrow, common problem: an element's children are added, removed or reordered by your framework, and the change happens instantly with no transition. It watches a container and animates the resulting DOM mutations. You point it at a parent element, and every child that enters, leaves or moves gets a transition.

The intended audience is application developers who already have working UI and want the polish of motion without adopting an animation framework. The README frames the pitch as adding motion "with a single line of code", and the package description repeats that phrasing. That is the whole scope. It does not animate arbitrary CSS properties, it does not give you a timeline, and it does not replace a library like GSAP or Motion for choreographed sequences.

This narrowness is the point. Most list animations in real apps are enter, exit and reorder. AutoAnimate covers those three cases with no configuration, which is why the API surface is so small.

## How the DOM watcher and transition lifecycle work

The mechanism is a parent-level observer. You attach AutoAnimate to a container element, and the library records the position of its children before a mutation, then compares after. Children that appear get an enter transition, children that disappear get an exit transition, and children that change position get a transform-based move.

The package ships framework-specific entry points rather than one universal build. The exports map in package.json defines subpaths for "./vue", "./preact", "./react", "./solid" and "./marko", each with its own types and ESM file. That means the React build is not a wrapper you configure; it is a separate module resolved by the bundler through the export condition. The package is marked "type": "module" and its main entry is index.mjs, so it is ESM-first.

The repository layout reflects the same split. There is a src/ directory for shared logic, a build/ directory with a build script, a docs/ site, tests/ with Playwright configuration, and a marko.json at the top level for the Marko tag integration. The package.json keywords list animation, transition, react, preact, vue, angular, svelte, solid and marko, though the exports map shown in the repository only defines subpaths for five of those frameworks. Angular and Svelte are named in keywords but do not appear as export subpaths, so treat those as unconfirmed until you check the installed package.

## Install with npm, pnpm or yarn and wire up React

Installation is a single package add. The README gives three package managers side by side, and the package name is scoped under @formkit.

```bash
npm install @formkit/auto-animate
```

After install, the framework-specific entry point is what you import. For React the export subpath is "./react", so the import path is @formkit/auto-animate/react. The README points to the documentation site for usage instructions rather than showing a React snippet inline, so the exact hook or ref signature is not reproduced here. What the repository does confirm is that the React build exists as a separate module with its own type declarations at react/index.d.ts.

The practical first use is: create a container that renders a list from state, attach AutoAnimate to that container, then push or remove items from the state array. The transitions should run on the next render without any transition classes or keyframes. If nothing animates, the first thing to check is that you attached it to the parent of the changing children, not to the children themselves.

## Where zero-config stops being enough

The limitation follows directly from the design. Because AutoAnimate infers transitions from DOM mutations, it has no vocabulary for timing curves, stagger delays or sequencing. If you need item three to start after item two finishes, that is outside what a mutation observer can express.

There is a second constraint worth naming: the utility animates layout changes to children of the element you attach it to. It is not a general-purpose animation layer for the page. Animating a modal's backdrop, a route transition between two different components, or an SVG path drawing are all different problems, and the README does not claim otherwise.

The repository does hint at extensibility. The README has a Plugins section linking to the documentation site, and package.json includes a test:e2e:visual script plus a test:e2e:leak script gated behind a LEAK_STRICT environment variable. The presence of a memory-leak test target suggests the maintainers treat long-lived observers as a real risk area, which is consistent with how any mutation-observing utility behaves in a single-page app that mounts and unmounts views repeatedly.

## AutoAnimate versus Framer Motion

The most common comparison is against Framer Motion, and the difference is architectural rather than cosmetic. Framer Motion asks you to declare animation on components: you wrap elements, specify initial and animate props, and the library drives the values. AutoAnimate asks you to declare nothing. You attach it to a container and it reacts to whatever your framework already did to the DOM.

That means Framer Motion can express things AutoAnimate cannot, including orchestrated sequences, gesture-driven motion and layout animations tied to specific props. It also means Framer Motion requires more code and more decisions per animated element. AutoAnimate trades expressiveness for the absence of configuration.

The trade-off is real in both directions. If your animation needs are enter, exit and reorder on lists, AutoAnimate will get you there faster and with less code to maintain. If you are building an interaction where the motion itself is the feature, you will hit the ceiling quickly and end up with both libraries in the bundle.

## Maintenance, licence and upgrade cost

The package is MIT licensed, stated in both the README and package.json. MIT permits commercial use, modification and redistribution with the licence and copyright notice retained. That is the standard permissive position; it is not legal advice, and if your organisation has a policy on attribution in bundled output, check how your build handles licence headers.

On maintenance, the facts are concrete. The repository is not archived. The last push to master was on 2026-07-10, and the most recent release listed is v0.10.0 on the same date. Before that, the release history jumps back to 0.8.2 in April 2024 and 0.8.1 in November 2023. So the cadence is bursty: long quiet periods punctuated by a release. That pattern matters if you depend on prompt fixes.

The version numbering is also worth noticing. Releases before v0.10.0 are tagged without the leading v (0.8.2, 0.8.1), while the newest carries it. All of these are pre-1.0, which in practice means the maintainers have not committed to API stability. The README does not document a migration path between minor versions, so pinning a version in your lockfile and reading the release notes before bumping is the safer pattern. The repository does include a release script using bumpp and the build script, which indicates releases are cut through an automated flow rather than by hand.

## What to check before adding it to a production bundle

Three things are worth verifying on your own machine, because the README does not cover them. First, confirm that the subpath export for your framework resolves after install: the exports map is the contract, and a bundler that ignores it will fail on the deep import. Second, confirm the ESM-only packaging works with your build. The package sets "type": "module" and ships index.mjs with no CommonJS main, so a legacy toolchain that expects require() will need a workaround.

Third, check the plugins documentation if you need behaviour beyond the defaults. The README links to it but does not describe the plugin API inline, so the shape of a custom plugin is not something you can infer from the repository README alone.

The docs site at auto-animate.formkit.com is the canonical source for usage and examples; the README defers to it for both. If the docs are thin on a specific case, the tests directory and the Playwright configuration are the next place to look, since the visual and memory test scripts imply the behaviour is exercised there.

## Conclusion

Adopt AutoAnimate when your interface already re-renders lists, toggles panels or swaps rows and you want motion without writing keyframes or transition classes. Skip it when you need choreographed timelines, scroll-driven sequences or SVG path drawing; this is a DOM-diff animator, not a timeline engine. Before committing, check the @formkit/auto-animate version your package manager resolves, confirm the subpath export for your framework exists in the installed package, and read the plugin section of the docs if you need custom transition behaviour. The last push to master was on 2026-07-10, so the codebase is current as of that date, but the README itself does not document rollback or upgrade paths between minor versions.

## FAQ

### How does formkit/auto-animate compare to Framer Motion?

AutoAnimate attaches to a container and animates whatever DOM mutations your framework produces, with no per-element configuration. Framer Motion requires you to declare animation on components, which allows orchestrated sequences and gesture-driven motion that AutoAnimate does not express.

### How do I install formkit/auto-animate?

Install the scoped package with your package manager of choice: npm install @formkit/auto-animate, or the yarn and pnpm equivalents shown in the README. Framework-specific code is then imported from a subpath such as @formkit/auto-animate/react.

### Does formkit/auto-animate work with React?

Yes. The package.json exports map defines a "./react" subpath with its own type declarations and ESM file, alongside subpaths for Vue, Preact, Solid and Marko. The README also names Angular and Svelte in the keywords list, but those do not appear as export subpaths in the repository.

### What kind of animation does formkit/auto-animate handle?

It animates children of a container you attach it to, covering elements that enter, leave or change position. It is not a timeline or keyframe engine, so staggered sequences and scroll-driven motion are outside its scope.

### What licence does formkit/auto-animate use?

MIT, as stated in both the README and package.json. That permits commercial use and modification provided the licence and copyright notice are retained.

## Sources

- [formkit/auto-animate on GitHub](https://github.com/formkit/auto-animate)
- [License: MIT](https://github.com/formkit/auto-animate/blob/master/LICENSE)
- [Project website](https://auto-animate.formkit.com)
- [README](https://github.com/formkit/auto-animate/blob/master/README.md)
- [Releases](https://github.com/formkit/auto-animate/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/formkit-auto-animate