# DotLottieV1 Class
API documentation for the DotLottieV1 class in dotlottie-js, for creating and managing older V1 dotLottie files.

# `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:**

```typescript
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:**
  ```typescript
  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:**
  ```typescript
  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):**
  ```typescript
  // 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:**
  ```typescript
  // 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:**
  ```typescript
  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):**
  ```typescript
  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:**

  ```typescript
  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](/docs/tools/dotlottie-js/reference/utilities)