DotLottieV1 Class API

The DotLottieV1 class is for users who need to specifically create or interact with the older V1 .lottie file format. It has a more limited feature set compared to DotLottie (V2), lacking support for themes and state machines.

For V2 files, V2 features, or automatic V1 to V2 conversion on load, use the DotLottie class instead.

Import:

import { DotLottieV1 } from "@dotlottie/dotlottie-js";

Constructor

Creates a new, empty DotLottieV1 instance.

new DotLottieV1(options?: DotLottieV1Options)

• Parameters:

  • options (optional): DotLottieV1Options - An object to configure the instance.

    • author?: string: Sets the author metadata for the manifest.

    • version?: string: Sets the version metadata for the manifest.

    • enableDuplicateImageOptimization?: boolean: If true, attempts to de-duplicate identical images. (Default: false)

• Returns: DotLottieV1 - A new DotLottieV1 instance.

• Example:

  const dotLottieV1 = new DotLottieV1({
    author: "Your Name",
    version: "1.0",
    enableDuplicateImageOptimization: true,
  });

Instance Methods

Managing Content

addAnimation(animationOptions: AnimationOptionsV1): this

Adds a Lottie animation to the V1 archive. Image and audio assets referenced in the animationOptions.data will be processed and bundled during the build() step.

• Parameters:

  • animationOptions: AnimationOptionsV1 - An object describing the animation.

    • id: string - Unique identifier for the animation.

    • data: Record<string, any> - The Lottie JSON animation data.

    • loop?: boolean

    • speed?: number

    • themeColor?: string

• Returns: this (the DotLottieV1 instance for chaining).

• Example:

  const lottieJson = {
    v: "5.5.2",
    fr: 30,
    ip: 0,
    op: 150,
    w: 512,
    h: 512,
    nm: "V1 Anim",
    ddd: 0,
    assets: [],
    layers: [],
  };
  dotLottieV1.addAnimation({
    id: "anim_v1",
    data: lottieJson,
    loop: true,
  });

Building and Exporting

Similar to the V2 DotLottie class, you must build the archive before exporting.

build(): Promise<this>

Asynchronously prepares and finalizes the V1 dotLottie archive. This processes animations, bundles assets, and creates the manifest.

• Returns: Promise<this> - The instance, once built.

• Example: await dotLottieV1.build();

toArrayBuffer(): Promise<ArrayBuffer>

Generates the V1 .lottie archive as an ArrayBuffer.

• Prerequisite: build() must have been called.

• Returns: Promise<ArrayBuffer>

toBlob(): Promise<Blob>

Asynchronously generates the V1 .lottie archive as a Blob. Primarily useful in browser environments.

• Prerequisite: build() must have been called beforehand.

• Returns: Promise<Blob> - A promise that resolves to a Blob object representing the .lottie file.

• Example (Browser):

  // Assuming dotLottieV1 instance is built
  const blob = await dotLottieV1.toBlob();
  // const url = URL.createObjectURL(blob);

toBase64(): Promise<string>

Asynchronously generates the V1 .lottie archive as a base64 encoded string.

• Prerequisite: build() must have been called beforehand.

• Returns: Promise<string> - A promise that resolves to a base64 string representation of the .lottie file.

• Example:

  // Assuming dotLottieV1 instance is built
  const base64String = await dotLottieV1.toBase64();

Loading Existing Files

async fromArrayBuffer(arrayBuffer: ArrayBuffer): Promise<DotLottieV1>

Asynchronously loads a V1 dotLottie animation from an ArrayBuffer into a new instance.

• Parameters: arrayBuffer: ArrayBuffer - The ArrayBuffer containing the V1 .lottie file data.

• Returns: Promise<DotLottie> - A promise that resolves to a new instance of DotLottieV1 class.

• Example:

  async function loadV1FromArrayBuffer(buffer) {
    try {
      const dotLottieV1 = await new DotLottieV1().fromArrayBuffer(buffer);
      console.log("Loaded V1 from ArrayBuffer:", dotLottieV1.animations.length, "animation(s)");
      return dotLottieV1;
    } catch (error) {
      console.error("Failed to load V1 from ArrayBuffer:", error);
    }
  }

async fromURL(url: string): Promise<DotLottieV1>

Asynchronously fetches and loads a V1 dotLottie animation from a URL into a new instance. Note: This method loads V1 data into a V1 instance. It does not perform V1->V2 conversion.

• Parameters: url: string - The URL of the V1 .lottie file.

• Returns: Promise<DotLottieV1> - A promise that resolves to a new instance of DotLottieV1 class.

• Example (Browser/Node.js with fetch):

  async function loadV1FromURL(fileUrl) {
    try {
      const dotLottieV1 = await new DotLottieV1().fromURL(fileUrl);
      console.log("Loaded V1 from URL:", dotLottieV1.animations.length, "animation(s)");
      return dotLottieV1;
    } catch (error) {
      console.error("Failed to load V1 from URL:", error);
    }
  }

Merging Instances

merge(...dotLotties: DotLottieV1[]): DotLottieV1

Creates and returns a new DotLottieV1 instance containing the merged content of the instance it is called on, plus all V1 instances passed as arguments. The original instances are not modified.

• Parameters: ...dotLotties: DotLottieV1[] - One or more DotLottieV1 instances to merge.

• Returns: DotLottieV1 - A new DotLottieV1 instance containing the combined animations.

• Throws: If any duplicate animation IDs are found across the combined set.

• Note: The merge operation itself is synchronous, but the returned instance must be built (await mergedInstance.build()) before exporting.

• Example:

  const dl1 = new DotLottieV1(); // Assume dl1 has content
  const dl2 = new DotLottieV1(); // Assume dl2 has different content with unique IDs
  
  try {
    const mergedV1 = dl1.merge(dl2);
    await mergedV1.build(); // Build the new instance
    // ... export merged V1 instance ...
  } catch (error) {
    console.error("V1 Merge failed (likely duplicate ID):", error);
  }

Next up: Standalone Utilities