\r\n\r\n## Table of contents\r\n\r\n- [Features](#features)\r\n- [Quick example](#quick-example)\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n- [Caching](#caching)\r\n- [API](#api)\r\n- [Optimizations](#optimizations)\r\n- [Server side rendering](#server-side-rendering)\r\n\r\n## Features\r\n\r\n- **rich:** `ngx-lottie` provides more opportunities to work with API exposed by Lottie\r\n- **strict:** all types of objects and events are available to you\r\n- **performant:** the `lottie-web` library can be loaded synchronously or on demand\r\n\r\n## Quick example\r\n\r\n```html\r\n\r\n```\r\n\r\n## Installation\r\n\r\nTo install `ngx-lottie` run the following command:\r\n\r\n```bash\r\nnpm i lottie-web ngx-lottie\r\n# Or if you use yarn\r\nyarn add lottie-web ngx-lottie\r\n```\r\n\r\n## Usage\r\n\r\nFirst, import the `LottieModule` into the `AppModule`:\r\n\r\n```typescript\r\nimport { NgModule } from '@angular/core';\r\nimport { LottieModule } from 'ngx-lottie';\r\nimport player from 'lottie-web';\r\n\r\n// Note we need a separate function as it's required\r\n// by the AOT compiler.\r\nexport function playerFactory() {\r\n return player;\r\n}\r\n\r\n@NgModule({\r\n imports: [LottieModule.forRoot({ player: playerFactory })],\r\n})\r\nexport class AppModule {}\r\n```\r\n\r\nThe `lottie-web` library can be loaded on demand using dynamic import. Webpack will load this library only when your animation gets rendered for the first time. Given the following code:\r\n\r\n```ts\r\nimport { NgModule } from '@angular/core';\r\nimport { LottieModule } from 'ngx-lottie';\r\n\r\nexport function playerFactory() {\r\n return import('lottie-web');\r\n}\r\n\r\n@NgModule({\r\n imports: [LottieModule.forRoot({ player: playerFactory })],\r\n})\r\nexport class AppModule {}\r\n```\r\n\r\nNow you can simply use the `ng-lottie` component and provide your custom options via the `options` binding:\r\n\r\n```typescript\r\nimport { Component } from '@angular/core';\r\nimport { AnimationItem } from 'lottie-web';\r\nimport { AnimationOptions } from 'ngx-lottie';\r\n\r\n@Component({\r\n selector: 'app-root',\r\n template: `\r\n \r\n `,\r\n})\r\nexport class AppComponent {\r\n options: AnimationOptions = {\r\n path: '/assets/animation.json',\r\n };\r\n\r\n animationCreated(animationItem: AnimationItem): void {\r\n console.log(animationItem);\r\n }\r\n}\r\n```\r\n\r\nAlso it's possible to use the `lottie` directive if you'd like to provide your own custom container and control it:\r\n\r\n```typescript\r\nimport { Component } from '@angular/core';\r\nimport { AnimationItem } from 'lottie-web';\r\nimport { AnimationOptions } from 'ngx-lottie';\r\n\r\n@Component({\r\n selector: 'app-root',\r\n template: `\r\n \r\n `,\r\n})\r\nexport class AppComponent {\r\n options: AnimationOptions = {\r\n path: '/assets/animation.json',\r\n };\r\n\r\n animationCreated(animationItem: AnimationItem): void {\r\n console.log(animationItem);\r\n }\r\n}\r\n```\r\n\r\nNotice that you will need to import the `LottieModule` into other modules as it exports `ng-lottie` component and `lottie` directive. But `forRoot` has to be called only once!\r\n\r\n## Caching\r\n\r\n`lottie-web` will load your JSON file every time when animation is created. When importing the `LottieModule` into the root module you can provide the `useCache` option:\r\n\r\n```ts\r\nimport { NgModule } from '@angular/core';\r\nimport { LottieModule } from 'ngx-lottie';\r\n\r\nexport function playerFactory() {\r\n return import('lottie-web');\r\n}\r\n\r\n@NgModule({\r\n imports: [\r\n LottieModule.forRoot({\r\n player: playerFactory,\r\n useCache: true,\r\n }),\r\n ],\r\n})\r\nexport class AppModule {}\r\n```\r\n\r\nThis will enable cache under the hood. Since the cache is enabled your JSON file will be loaded only once.\r\n\r\n## API\r\n\r\n### Bindings\r\n\r\nThe `ng-lottie` component supports the following bindings:\r\n\r\n```ts\r\n@Component({\r\n selector: 'app-root',\r\n template: `\r\n \r\n `,\r\n})\r\nexport class AppComponent {\r\n options: AnimationOptions = {\r\n path: '/assets/animation.json',\r\n };\r\n\r\n styles: Partial = {\r\n maxWidth: '500px',\r\n margin: '0 auto',\r\n };\r\n}\r\n```\r\n\r\n- `options: AnimationOptions` options used by `AnimationItem`\r\n- `width?: string` container element width in pixels. Bound to `[style.width]`. You can provide any CSS unit, e.g. `100em`\r\n- `height?: string` container element height in pixels. Bound to `[style.height]`. You can provide any CSS unit, e.g. `100em`\r\n- `styles?: Partial` custom styles object. Bound to `[ngStyle]`\r\n- `containerClass?: string` custom container class(es). Bound to `[ngClass]`.\r\n\r\nThe `lottie` directive supports only `options` binding.\r\n\r\n### Events\r\n\r\n| @Output() | Type | Required | Description |\r\n| ---------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |\r\n| animationCreated | `AnimationItem` | optional | Dispatched after the `lottie` successfully creates animation |\r\n| configReady | `void` | optional | Dispatched after the needed renderer is configured |\r\n| dataReady | `void` | optional | Dispatched when all parts of the animation have been loaded |\r\n| domLoaded | `void` | optional | Dispatched when elements have been added to the DOM |\r\n| enterFrame | `BMEnterFrameEvent` | optional | Dispatched after entering the new frame |\r\n| segmentStart | `BMSegmentStartEvent` | optional | Dispatched when the new segment is adjusted |\r\n| loopComplete | `BMCompleteLoopEvent` | optional | Dispatched after completing frame loop |\r\n| complete | `BMCompleteEvent` | optional | Dispatched after completing the last frame |\r\n| destroy | `BMDestroyEvent` | optional | Dispatched in the `ngOnDestroy` hook of the service that manages `lottie`'s events, it's useful for releasing resources |\r\n| error | `BMRenderFrameErrorEvent OR BMConfigErrorEvent` | optional | Dispatched if the lottie player could not render some frame or parse the config |\r\n\r\n## Optimizations\r\n\r\nThe `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.\r\n\r\n`AnimationItem` events are listened outside of the Angular zone. You shouldn't worry that animation events will cause change detection every ms.\r\n\r\n**But be careful!** Always wrap any calls to `AnimationItem` methods in `runOutsideAngular`. See the below code:\r\n\r\n```ts\r\nimport { Component, NgZone } from '@angular/core';\r\nimport { AnimationItem } from 'lottie-web';\r\nimport { AnimationOptions } from 'ngx-lottie';\r\n\r\n@Component({\r\n selector: 'app-root',\r\n template: `\r\n \r\n\r\n \r\n \r\n `,\r\n})\r\nexport class AppComponent {\r\n options: AnimationOptions = {\r\n path: '/assets/animation.json',\r\n };\r\n\r\n private animationItem: AnimationItem;\r\n\r\n constructor(private ngZone: NgZone) {}\r\n\r\n animationCreated(animationItem: AnimationItem): void {\r\n this.animationItem = animationItem;\r\n }\r\n\r\n stop(): void {\r\n this.ngZone.runOutsideAngular(() => this.animationItem.stop());\r\n }\r\n\r\n play(): void {\r\n this.ngZone.runOutsideAngular(() => this.animationItem.play());\r\n }\r\n}\r\n```\r\n\r\n## Server side rendering\r\n\r\nBy default, `lottie` will load your `json` file with animation data every time you create an animation. You may have some problems with the connection, so there may be some delay or even timeout. It's worth loading animation data only once and cache it on the client side, so every time you create an animation — the animation data will be retrieved from cache.\r\n\r\n`ngx-lottie/server` package gives you the opportunity to preload animation data and cache it using `TransferState`.\r\n\r\n### How2?\r\n\r\nTL;DR - see `integration` folder.\r\n\r\nImport the `LottieServerModule` into your `AppServerModule`:\r\n\r\n```typescript\r\nimport { NgModule } from '@angular/core';\r\nimport { ServerModule, ServerTransferStateModule } from '@angular/platform-server';\r\nimport { LottieServerModule } from 'ngx-lottie/server';\r\n\r\nimport { AppModule } from './app.module';\r\nimport { AppComponent } from './app.component';\r\n\r\n@NgModule({\r\n imports: [\r\n // `AppModule` first as you know\r\n AppModule,\r\n ServerModule,\r\n ServerTransferStateModule,\r\n LottieServerModule.forRoot({\r\n preloadAnimations: {\r\n folder: 'dist/assets',\r\n animations: ['data.json'],\r\n },\r\n }),\r\n ],\r\n bootstrap: [AppComponent],\r\n})\r\nexport class AppServerModule {}\r\n```\r\n\r\nDon't forget to import `BrowserTransferStateModule` into your `AppModule`. Let's look at these options. `animations` is an array of `json` files, that contain animation data, that should be read on the server side, cached and transfered on the client. `folder` is a path where your `json` files are located, but you should use it properly, this path is joined with the `process.cwd()`. Imagine such project structure:\r\n\r\n```\r\n— dist (here you store your output artifacts)\r\n — project-name\r\n — assets\r\n — index.html\r\n — main.hash.js\r\n— dist-server\r\n — server.js\r\n— src (here is your app)\r\n— angular.json\r\n— package.json\r\n— webpack.config.js\r\n```\r\n\r\nIf you start a server from the root folder like `node dist-server/server`, thus the `folder` property should equal `dist/project-name/assets`.\r\n\r\nAfter installing `LottieServerModule` - now you have to import `LottieTransferState` from the `ngx-lottie` package. Don't worry, this service is tree-shakable and won't be bundled if you don't inject it anywhere.\r\n\r\nInject this service into your component where you declare animation options:\r\n\r\n```typescript\r\nimport { Component } from '@angular/core';\r\nimport { AnimationOptions, LottieTransferState } from 'ngx-lottie';\r\n\r\n@Component({\r\n selector: 'app-root',\r\n template: `\r\n \r\n `,\r\n})\r\nexport class AppComponent {\r\n options: AnimationOptions = {\r\n animationData: this.lottieTransferState.get('data.json'),\r\n };\r\n\r\n constructor(private lottieTransferState: LottieTransferState) {}\r\n}\r\n```\r\n\r\nNotice, `data.json` is a filename that you pass to the `preloadAnimations.animations` property. Finally change this:\r\n\r\n```typescript\r\nplatformBrowserDynamic().bootstrapModule(AppModule);\r\n```\r\n\r\nTo this:\r\n\r\n```typescript\r\ndocument.addEventListener('DOMContentLoaded', () => {\r\n platformBrowserDynamic().bootstrapModule(AppModule);\r\n});\r\n```\r\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/ngx-lottie/ngx-lottie/master/docs/assets/lottie.gif\")
\r ![\"CircleCI\"](\"https://circleci.com/gh/ngx-lottie/ngx-lottie/tree/master.svg?style=svg\")
\r\n ![\"Licence:](\"https://img.shields.io/badge/License-MIT-brightgreen.svg\"){kind=icon}
\r\n ![\"npm](\"https://badge.fury.io/js/ngx-lottie.svg\"){kind=icon}
\r\n ![\"David\"](\"https://img.shields.io/david/ngx-lottie/ngx-lottie.svg\")
\r\n