ng-auto-animate

An Angular Directive for FormKit's auto-animate library.

Demo → https://ng-auto-animate.netlify.app/

Highlights

• ✅ Standalone Directive, for Angular v17 and above.
• ✅ Zoneless & signals-first. RxJS is not required.
• ✅ Custom InjectionToken for configuring global settings and plugins.
• ✅ SSR-safe, running only after the view is initialized on the client-side.

Installation

Install this package and its peer dependency with the package manager of your choice.

npm i ng-auto-animate @formkit/auto-animate

pnpm i ng-auto-animate @formkit/auto-animate

bun add ng-auto-animate @formkit/auto-animate

yarn add ng-auto-animate @formkit/auto-animate

Usage

Principle

Add the directive to the parent tag, within which DOM elements are being dynamically shown or hidden.

Applying the directive to the same tag being hidden will have no effect, as it only detects changes in child nodes.

Import Path

Import and add the directive to your module or standalone component's imports array.

import { NgAutoAnimate } from 'ng-auto-animate';

Variants

1. Default usage. This uses the default values configured by @formkit/auto-animate.

   <article auto-animate>
     @if (shouldShow()) {
       <p>Conditionally shown element</p>
     }
   </article>

2. Pass one-off options. Inline options will completely replace and override the default options.

   <article [auto-animate]="{ duration: 750 }">
     @if (shouldShow()) {
       <p>{{ paragraph }}</p>
     }
   </article>

3. Global options. The ideal place to configure standard settings across your app. The supported values are Partial<AutoAnimateOptions> | AutoAnimationPlugin

   // src/app/app.config.ts
   import { ApplicationConfig } from '@angular/core';
   import { provideAutoAnimateConfig } from 'ng-auto-animate';
   import type {
     AutoAnimateOptions, // Standard options like easing, duration, etc.
     AutoAnimationPlugin, // Custom plugins
   } from '@formkit/auto-animate';
   
   export const appConfig: ApplicationConfig = {
     providers: [
       provideAutoAnimateConfig({ duration: 1000, easing: 'ease-out' }),
     ],
   };
   
   // main.ts
   import { bootstrapApplication } from '@angular/platform-browser';
   import { appConfig } from './app/app.config';
   import { App } from './app/app';
   
   bootstrapApplication(App, appConfig).catch(err => console.error(err));

   <article auto-animate>
     <!-- Default usage -->
     @for (paragraph of paragraphs; track paragraph) {
       <p>{{ paragraph }}</p>
     }
   </article>

4. Custom plugins. Same support as @formkit/auto-animate.

   See the example here in the demo app for a "bouncy" effect.

   customPlugin: AutoAnimationPlugin = (...) => {...};

   <article [auto-animate]="customPlugin">...</article>

5. Disable animations. prefers-reduced-motion is already respected. Additionally, we can explicitly disable animations like this:

   <article
     [auto-animate]="{ duration: 750 }"
     [disableAutoAnimate]="shouldDisableAnimations()"
   >
     @if (shouldShow()) {
       <p>{{ paragraph }}</p>
     }
   </article>

Missing support for something?

Go through existing issues if your problem is tracked; if not, please raise a new issue!

Support us

Is AutoAnimate saving you time?

Please consider supporting us with a recurring or one-time donation! 🙏

License

MIT.

Built by Ajit Panigrahi. Original library by Justin Schroeder and many contributors.