ngx-lottie

A minimal customizable performance-stable Angular component for rendering After Effects animations.

Table of contents

• Features
• Quick example
• Installation
• Usage
• API
• Optimizations

Features

• rich: ngx-lottie provides more opportunities to work with API exposed by Lottie
• strict: all types of objects and events are available to you
• performant: the lottie library is loaded on demand

Quick example

<ng-lottie
  width="600"
  height="500"
  containerClass="moving-box"
  [options]="options"
  (animationCreated)="animationCreated($event)"
  (configReady)="configReady()"
  (dataReady)="dataReady()"
  (domLoaded)="domLoaded()"
  (enterFrame)="enterFrame($event)"
  (segmentStart)="segmentStart($event)"
  (complete)="complete($event)"
  (loopComplete)="loopComplete($event)"
  (destroy)="destroy($event)"
></ng-lottie>

Installation

To install ngx-lottie run the following command:

npm i ngx-lottie
# or if you're using yarn
yarn add ngx-lottie

Usage

First, import the LottieModule to any of your modules:

import { NgModule } from '@angular/core';
import { LottieModule } from 'ngx-lottie';

@NgModule({
  imports: [
    LottieModule
  ]
})
export class AppModule {}

Now you can simple use an ng-lottie component and provide your custom options via the options binding:

import { Component } from '@angular/core';
import { LottieOptions, AnimationItem } from 'ngx-lottie';

@Component({
  selector: 'app-root',
  template: `
    <ng-lottie
      [options]="options"
      (animationCreated)="animationCreated($event)"
    ></ng-lottie>
  `
})
export class AppComponent {
  public options: LottieOptions = {
    path: '/assets/animation.json'
  };

  public animationCreated(animationItem: AnimationItem): void {
    console.log(animationItem);
  }
}

Also it's possible to use a lottie directive if you'd like to provide your own custom container and play with it:

import { Component } from '@angular/core';
import { LottieOptions, AnimationItem } from 'ngx-lottie';

@Component({
  selector: 'app-root',
  template: `
    <main
      lottie
      [options]="options"
      (animationCreated)="animationCreated($event)"
    ></main>
  `
})
export class AppComponent {
  public options: LottieOptions = {
    path: '/assets/animation.json'
  };

  public animationCreated(animationItem: AnimationItem): void {
    console.log(animationItem);
  }
}

API

Bindings

@Input()	Type	Required	Default	Description
options	LottieOptions	required	{ renderer: 'svg', loop: true, autoplay: true }	Configuration that's used by AnimationItem
width	string	optional	null	Custom container width
height	string	optional	null	Custom container height
styles	LottieCSSStyleDeclaration	optional	null	Custom container styles
containerClass	LottieContainerClass	optional	null	Custom class applied to the container

Events

@Output()	Type	Required	Description
animationCreated	AnimationItem	optional	Dispatched after the lottie successfully creates animation
configReady	void	optional	Dispatched after the needed renderer is configured
dataReady	void	optional	Dispatched when all parts of the animation have been loaded
dataFailed	void	optional	Dispatched if the XMLHttpRequest, that tried to load animation data using provided path, has errored
domLoaded	void	optional	Dispatched when elements have been added to the DOM
enterFrame	BMEnterFrameEvent	optional	Dispatched after entering the new frame
segmentStart	BMSegmentStartEvent	optional	Dispatched when the new segment is adjusted
loopComplete	BMCompleteLoopEvent	optional	Dispatched after completing frame loop
complete	BMCompleteEvent	optional	Dispatched after completing the last frame
loadedImages	void	optional	Dispatched after all assets are preloaded
destroy	BMDestroyEvent	optional	Dispatched in the ngOnDestroy hook of the service that manages lottie's events, it's useful for releasing resources

Optimizations

The ng-lottie component is marked with OnPush change detection strategy. This means it will not be checked in any phase of the change detection mechanism until you change the reference to some binding. For example if you use an svg renderer and there are a lot DOM elements projected - you would like to avoid checking this component, as it's not necessary.

Also, events, dispatched by AnimationItem, are listened outside Angular's zone, thus you shouldn't worry that every dispatch will be intercepted by Angular's zone.