ng-auto-animate

An Angular Directive to use FormKit's auto-animate library within Angular projects.

Highlights

• ✅ Standalone Directive, for Angular v14 and above. Tested on Node 18.x, but should work on previous versions.
• ✅ Custom InjectionToken for configuring global settings and plugins.

Why a new wrapper library?

A publishable library for Angular needs ng-packagr and Angular CLI for proper scaffolding and finalized formatting. Migrating the repository structure for auto-animate is a non-trivial task and would need an unbiased build system like Nx (which I am using here) or some other similar tool.

Justin Schroeder, the creator of auto-animate, has been supportive towards contributions for Angular integration, but he does not work with Angular and is unable to work towards this actively. I, too, would not be able to do much in his shoes, especially when it requires replacing all build actions, scripts and the project structure, all to support a single framework.

If there is a simpler solution, I would be willing to submit a PR with my changes here to the original project, especially the support for global options/plugin via an InjectionToken.

Installation

1. Install the peer dependency.

   npm i @formkit/auto-animate

2. Install this package.

   npm i ng-auto-animate

Usage

Principle

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

Adding the directive to the same tag which is being hidden will do nothing since it will look for changes in child nodes only.

Import Path

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

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

Variants

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

   <article auto-animate>
     <p *ngFor="let paragraph of paragraphs">
       {{ paragraph }}
     </p>
   </article>

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

   <article [auto-animate]="{ duration: 750 }">
     <p *ngFor="let paragraph of paragraphs">
       {{ paragraph }}
     </p>
   </article>

3. Global options. The ideal place to configure common settings across your app.

   // src/app/app.config.ts
   import { ApplicationConfig } from '@angular/core';
   import { GLOBAL_AUTO_ANIMATE_OPTIONS } from 'ng-auto-animate';
   
   export const appConfig: ApplicationConfig = {
     providers: [
       {
         provide: GLOBAL_AUTO_ANIMATE_OPTIONS,
         useValue: {
           duration: 750,
           easing: 'ease-out',
           // etc.
         },
       },
       // other providers
     ],
   };
   
   // main.ts
   import { bootstrapApplication } from '@angular/platform-browser';
   import { appConfig } from './app/app.config';
   import { AppComponent } from './app/app.component';
   
   bootstrapApplication(AppComponent, appConfig).catch((err) =>
     console.error(err)
   );

   <article auto-animate> <!-- Default usage -->
     <p *ngFor="let paragraph of paragraphs">
       {{ 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>

Missing support for something?

Go through existing issues if your problem is already being tracked; otherwise, raise an issue!

License

MIT.

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

This library was generated with Nx.