# dotLottie Format V1 vs V2
Compare dotLottie format V1 and V2. Learn how dotlottie-js handles versions with DotLottie and DotLottieV1 classes, for modern and legacy needs.

# Format Versions: V1 vs. V2 & Library Handling

The dotLottie format has evolved, with version 2 (V2) introducing significant enhancements over version 1 (V1). Understanding these differences and how `dotlottie-js` handles them is important for effective use of the library.

## dotLottie File Format: V1 vs. V2

Here are the key distinctions at the file format level:

| Feature                                                                            | dotLottie V1                           | dotLottie V2                                                                                                                                                 |
| :--------------------------------------------------------------------------------- | :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manifest**                                                                       | `manifest.json` is simpler.            | `manifest.json` is more structured and includes explicit sections for themes and state machines. Can also include more detailed metadata.                    |
| **[Theming](/docs/tools/dotlottie-js/how-to-guides/manage-themes)**                | Not natively supported.                | **Supported.** Themes (e.g., color palettes, property overrides) can be defined as separate JSON files (in a `t/` directory) and referenced in the manifest. |
| **[State Machines](/docs/tools/dotlottie-js/how-to-guides/manage-state-machines)** | Not natively supported.                | **Supported.** State machines for interactive animations can be defined as separate JSON files (in an `s/` directory) and referenced in the manifest.        |
| **Directory Structure**                                                            | Primarily `animations/` and `images/`. | More comprehensive: `a/` (animations), `i/` (images), `u/` (audio), `t/` (themes), and `s/` (state machines) directories as needed.                          |
| **Asset Referencing**                                                              | Basic path-based referencing.          | More robust referencing, facilitating complex interactions with themes and states.                                                                           |
| **Extensibility**                                                                  | Limited.                               | Designed for better extensibility and future features.                                                                                                       |

In essence, **V2 is the current standard** and offers a much richer feature set, especially for creating interactive and themable Lottie experiences.

## `dotlottie-js` Library Handling of Versions

`dotlottie-js` is designed with a **V2-first approach** but provides compatibility with V1 files.

### 1. `DotLottie` Class (V2 Focus)

- The main [`DotLottie`](/docs/tools/dotlottie-js/reference/dotlottie-class) class is designed primarily for the V2 format and its features (themes, state machines).
- When loading data (`fromArrayBuffer`, `fromURL`), it automatically detects V1 `.lottie` files and **upgrades them internally** to a V2 structure.
- This means even if you load a V1 file, you interact with it using the V2 API (e.g., accessing `dotlottie.animations`).
- Adding V2 features (like themes or state machines) to an instance loaded from a V1 file will result in a V2 file upon export.
- **Recommendation:** For new projects and to leverage the full capabilities of dotLottie, using `new DotLottie()` is strongly recommended.

### 2. `DotLottieV1` Class

- If you explicitly need to **create** or work strictly with the V1 format without automatic conversion or V2 features, use the [`DotLottieV1`](/docs/tools/dotlottie-js/reference/dotlottie-v1-class) class.
- `new DotLottieV1()` creates an instance that adheres to the V1 structure.

### 3. `makeDotLottie()` Utility

- The `makeDotLottie()` utility function is also exported. See [`makeDotLottie()`](/docs/tools/dotlottie-js/reference/utilities#makedotlottie).
- This is a generic factory function. To create a `DotLottieV1` instance, you must pass the version argument: `makeDotLottie('v1')`.
- Passing `'v2'` creates a `DotLottie` (V2) instance: `makeDotLottie('v2')`. The `version` argument is required.

**In Summary:**

- **Default to `new DotLottie()`:** It provides the most modern, feature-rich experience and handles V1 files gracefully by upgrading them internally.
- **Use `new DotLottieV1()` or `makeDotLottie('v1')` only if:** You have a specific requirement to _generate_ a V1 format file and do not need V2 features.

Understanding these differences helps choose the right tool for your task.

## manifest.json Reference

Every `.lottie` file contains a `manifest.json` at its root describing the contents:

- `version`: Format version (e.g., `"2"` for V2).
- `generator`: Tool/library used to produce the file (e.g., `"@dotlottie/dotlottie-js@x.y.z"`).
- `animations`: Array listing Lottie animations. Each entry includes an `id` and can have `name`, `initialTheme`, etc. See [Manage Animations](/docs/tools/dotlottie-js/how-to-guides/manage-animations). Animation JSON is stored at `a/<animation_id>.json`.
- `themes` (Optional, V2+): Array listing theme definitions. See [Manage Themes](/docs/tools/dotlottie-js/how-to-guides/manage-themes). Theme data is stored at `t/<theme_id>.json`.
- `stateMachines` (Optional, V2+): Array listing state machine definitions. See [Manage State Machines](/docs/tools/dotlottie-js/how-to-guides/manage-state-machines). State machine data is stored at `s/<state_machine_id>.json`.
- `activeAnimationId` (Optional): ID of the default animation to play.
- `author`, `description`, `keywords`, `custom` data fields.

Next up: [Create and Export a `.lottie` File](/docs/tools/dotlottie-js/how-to-guides/create-and-export-a-lottie-file)