What is dotlottie-js?

dotlottie-js is a JavaScript library engineered for developers who need to programmatically create, read, and manipulate dotLottie (.lottie) files. It operates seamlessly in both browser and Node.js environments, offering a comprehensive API for managing Lottie animations and their associated assets within the dotLottie V2 specification.

Purpose and Key Functions

dotlottie-js provides a robust and developer-friendly interface for working with the dotLottie format. Key functions include:

• Creating dotLottie Archives: Programmatically bundle one or more Lottie JSON animations, image assets (PNG, JPEG), and audio assets into a single, optimized .lottie file.

• Reading and Parsing: Load .lottie files from various sources (like URLs in the browser or ArrayBuffers) and parse their contents, including animations, assets, themes, and state machines.

• Manipulation: Add, remove, or modify animations within a dotLottie instance. Manage themes and state machines for advanced control over animation behavior and appearance.

• Asset Management: Handle the inclusion and referencing of image and audio assets tied to specific animations.

• Exporting: Generate .lottie files in different formats, such as ArrayBuffer (suitable for storage or further processing), Blob (for browser environments), or Base64 encoded strings. The library also facilitates direct downloads in browser contexts.

• Accessing Metadata: Read and modify manifest information like version, generator, author, and custom data.

Two Ways to Work: The DotLottie Class and Standalone Utilities

dotlottie-js offers a flexible approach to managing .lottie files, catering to different needs and preferences:

1. The DotLottie Class: For comprehensive management of a .lottie instance, the DotLottie class is your primary tool. It allows you to build up an archive with multiple animations, assets, themes, and state machines, then export the result. This object-oriented approach is ideal for complex manipulations and when working with the full V2 feature set.

2. Standalone Utility Functions: For more targeted operations or when you don't need to manage a full instance, dotlottie-js also exports a suite of standalone utility functions. These functions provide direct access to common tasks like extracting specific animations, images, or themes from a .lottie buffer, checking asset types, or converting between format versions without needing to instantiate a DotLottie object. They are powerful helpers for quick, specific tasks.

This dual approach ensures you have both a high-level, instance-based API and granular, functional tools at your disposal.

Focus on dotLottie V2 Features

While dotlottie-js can load and convert V1 dotLottie files, its core design and API center around the dotLottie V2 specification. This provides first-class support for advanced V2 features, enabling you to:

• Implement Theming: Define and manage multiple themes within a single .lottie file. This allows animations to dynamically change their appearance (e.g., colors, properties) at runtime without requiring separate animation files for each visual style.

• Build Interactive Animations with State Machines: Create and configure state machines to control animation playback based on user interactions, events, or application logic. This opens up possibilities for complex, interactive Lottie experiences.

By focusing on V2, dotlottie-js ensures that developers can leverage the latest and most powerful capabilities of the dotLottie format.

When to Use dotlottie-js

This library is ideal if you are:

• Building tools that automate the creation or modification of .lottie files.

• Integrating dotLottie generation into a backend system or CMS.

• Developing plugins or scripts that process Lottie animations and package them into the dotLottie format.

• Need to programmatically apply themes or state machines to Lottie animations.

If you are looking to simply play .lottie animations, a dedicated dotLottie Player for your target platform (web, mobile, etc.) is the more appropriate tool. dotlottie-js is for working with the file format itself.

Next up: Getting Started & Installation