angular-dotlottie v1.0.0

Angular DotLottie

An Angular wrapper for the @dotlottie/player-component library, which allows you to easily integrate .lottie animations into your Angular applications.

Features

• 🚀 Easy integration with Angular projects
• 🎨 Full support for all DotLottie features
• 🔄 Two-way data binding for animation controls
• 📦 Component and directive approaches for flexibility
• 🛠 TypeScript support
• 🎬 Event emitters for animation lifecycle events
• 🔧 Zone-optimized for performance

Installation

npm install angular-dotlottie @dotlottie/player-component

Basic Usage

1. Import the Module

Add the AngularDotLottieModule to your app module:

import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { AngularDotLottieModule } from "angular-dotlottie";

import { AppComponent } from "./app.component";

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AngularDotLottieModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

2. Component Approach

Use the ng-dotlottie-player component in your templates:

<ng-dotlottie-player src="assets/animations/animation.lottie" [autoplay]="true" [loop]="true" [controls]="true" (ready)="onAnimationReady($event)" (complete)="onAnimationComplete($event)"> </ng-dotlottie-player>

3. Directive Approach

Use the ngDotLottie directive on any element:

<div [ngDotLottie]="'assets/animations/animation.lottie'" [autoplay]="true" [loop]="true"></div>

API Reference

Inputs

Outputs (Events)

Methods

Enums

enum PlayMode {
  Forward = "forward",
  Reverse = "reverse",
  Bounce = "bounce",
}

Advanced Usage

Controlling Animations with ViewChild

import { Component, ViewChild } from "@angular/core";
import { DotLottiePlayerComponent, PlayMode } from "angular-dotlottie";

@Component({
  selector: "app-animation-controller",
  template: `
    <ng-dotlottie-player #player src="assets/animations/animation.lottie" [loop]="true"> </ng-dotlottie-player>

    <div class="controls">
      <button (click)="player.playAnimation()">Play</button>
      <button (click)="player.pauseAnimation()">Pause</button>
      <button (click)="player.stopAnimation()">Stop</button>
      <button (click)="changeSpeed(2)">2x Speed</button>
      <button (click)="player.takeSnapshot(true)">Download Snapshot</button>
    </div>
  `,
})
export class AnimationControllerComponent {
  @ViewChild("player") player: DotLottiePlayerComponent;

  changeSpeed(speed: number): void {
    this.player.setSpeed(speed);
  }
}

Dynamic Animation Loading

import { Component } from "@angular/core";
import { DotLottiePlayerComponent, PlayMode } from "angular-dotlottie";

@Component({
  selector: "app-dynamic-animations",
  template: `
    <ng-dotlottie-player #player [loop]="true" [autoplay]="true"> </ng-dotlottie-player>

    <div class="animation-selector">
      <button (click)="loadAnimation('success')">Success</button>
      <button (click)="loadAnimation('error')">Error</button>
      <button (click)="loadAnimation('loading')">Loading</button>
    </div>
  `,
})
export class DynamicAnimationsComponent {
  @ViewChild("player") player: DotLottiePlayerComponent;

  animations = {
    success: "assets/animations/success.lottie",
    error: "assets/animations/error.lottie",
    loading: "assets/animations/loading.lottie",
  };

  loadAnimation(animationKey: keyof typeof this.animations): void {
    this.player.loadAnimation(this.animations[animationKey]);
  }
}

Custom Animation Service

import { Injectable } from "@angular/core";
import { PlayMode } from "angular-dotlottie";

@Injectable({
  providedIn: "root",
})
export class AnimationService {
  private baseUrl = "assets/animations/";

  getAnimationPath(name: string): string {
    return `${this.baseUrl}${name}.lottie`;
  }

  getDefaultConfig(type: "indicator" | "feedback" | "illustration") {
    switch (type) {
      case "indicator":
        return { loop: true, autoplay: true, mode: PlayMode.Forward };
      case "feedback":
        return { loop: false, autoplay: true, mode: PlayMode.Forward };
      case "illustration":
        return { loop: true, autoplay: false, mode: PlayMode.Forward };
    }
  }
}

Browser Support

Angular DotLottie supports all browsers that are supported by Angular and the DotLottie player component.

Troubleshooting

Animation Not Displaying

1. Make sure your .lottie file path is correct
2. Check that the container has a non-zero width and height
3. Verify that the animation file is a valid .lottie format

Performance Issues

The component runs animations outside of Angular's zone for better performance. If you experience issues:

1. Make sure you're not manually triggering change detection excessively
2. Consider using simpler animations for mobile devices
3. Set [controls]="false" to reduce DOM elements

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• DotLottie Web - The core player this wrapper is built upon
• LottieFiles - For creating the DotLottie format

Made with ❤️ for the Angular community