Ngx-dotlottie-web

Contents

• Introduction
  • What is dotLottie?
• Installation
• Basic Usage
• Live Examples
• APIs
  • DotLottieWebComponent
  • DotLottieWebworkerComponent
• Listening to Events
• Development
  • Setup
  • Dev
  • Build
  • Test

Introduction

An Angular library for rendering lottie and dotLottie animations in the browser.

What is dotLottie?

dotLottie is an open-source file format that aggregates one or more Lottie files and their associated resources into a single file. They are ZIP archives compressed with the Deflate compression method and carry the file extension of ".lottie".

Learn more about dotLottie.

Installation

This package relies on the @lottiefiles/dotlottie-web package. You can install this package using npm:

npm install @lottiefiles/dotlottie-web ngx-dotlottie-web

Basic Usage

Import and use the components in your Angular application:

// app.component.ts
import { DotLottieWebComponent } from 'ngx-dotlottie-web/src/web';
import { DotLottieWebWorkerComponent } from 'ngx-dotlottie-web/src/webworker';

@Component({
  // ...
  imports: [DotLottieWebComponent, DotLottieWebWorkerComponent],
  // ...
})

Basic usage in your template:

<!-- Regular dotLottie player -->
<dotlottie-web
  [src]="'path/to/animation.lottie'"
  [autoplay]="true"
  [loop]="true"
></dotlottie-web>

<!-- Web Worker based player (better performance) -->
<dotlottie-webworker
  [src]="'path/to/animation.lottie'"
  [autoplay]="true"
  [loop]="true"
  workerId="unique-worker-id"
></dotlottie-webworker>

Live Examples

Demo

APIs

DotLottieWebComponent

DotLottieWebComponent Input Props

The DotLottieWebComponent accepts the following props with their detailed primitive types:

Prop	Type	Description
autoplay	boolean	Enables or disables automatic playback of the animation.
backgroundColor	string	Sets the background color of the animation.
src	string	Specifies the source URL or data for the animation.
layout	string	Determines the layout configuration for rendering.
loop	boolean	Controls whether the animation should loop.
marker	string	Defines markers within the animation timeline.
mode	string	Sets the rendering mode for the animation.
autoResize	boolean	Enables automatic resizing of the animation canvas.
freezeOnOffscreen	boolean	Freezes the animation when it goes offscreen.
devicePixelRatio	number	Adjusts rendering based on the device’s pixel ratio.
segment	Array<number, number>	Specifies starting and ending frames for segmented playback.
speed	number	Sets the playback speed of the animation.
themeId	string	Identifies the theme to be applied.
animationId	string	Optional identifier for the animation instance.
useFrameInterpolation	boolean	Enables frame interpolation for smoother animations.
canvasClass	string | string[]	CSS classes to be applied to the canvas element.
freeze	boolean	Manually freezes the animation playback.
play	boolean	Triggers playback of the animation.
stop	boolean	Stops the animation playback.

DotLottieWebworkerComponent

DotLottieWebworkerComponent Input Props

Accepts the same input props as the DotLottieWebComponent in addition to the following:

Prop	Type	Description
workerId	string	Unique identifier for the web worker instance.

Listening to Events

Output Props

Prop	Type	Description
lottieInit	DotLottie or DotLottieWorker instance	Emits the lottie instance when it's initialized (either rendered directly or via a web worker).

You can listen to regular lottie events and perform direct actions with the lottie instance.

Here is an example. In your component's template, bind to the lottieInit output:

<dotlottie-web
  [src]="'path/to/animation.lottie'"
  [autoplay]="true"
  (lottieInit)="onLottieInit($event)">
</dotlottie-web>

In the corresponding TypeScript file, define the handler:

import { Component } from '@angular/core';

@Component({
  selector: 'app-animation',
  templateUrl: './animation.component.html'
})
export class AnimationComponent {
  onLottieInit(lottieInstance: any) {
    console.log('Lottie initialized:', lottieInstance);
    // Custom logic with the lottie instance
  }
}

dotLottie instance exposes multiple events that can be listened to. You can find the list of events here.

Development

Setup

Clone the repository and install dependencies using your preferred package manager (e.g., pnpm):

git clone https://github.com/victor-enogwe/ngx-dotlottie-web.git
cd ngx-dotlottie-web
pnpm install

Dev

For local development, run the development server to see live changes:

pnpm start

Build

To compile the library for production, use:

pnpm run build

You can also build the demo project with:

pnpm run build:demo

Testing

Run unit tests with Jest:

pnpm test

For end-to-end tests:

pnpm test:e2e

To launch Cypress for interactive testing:

pnpm cypress:open

License

MIT