.lottie Format Specification

The .lottie format is a modern container format for Lottie animations that packages animations, assets, themes, and interactivity into a single file. It uses ZIP compression and includes a manifest for metadata and configuration.

Version

Current specification version: 2

For the legacy v1 specification, see dotLottie v1.0 Specification.

Format Overview

A .lottie file is a ZIP archive containing:

One or more Lottie JSON animations
Image and font assets
A manifest.json file describing the contents
Optional state machines for interactivity
Optional themes for dynamic styling

MIME Type

application/zip+dotlottie

File Extension

.lottie

Archive Structure

.
├─ manifest.json          # Required: Metadata file describing the package
├─ a/                     # Required: Directory containing Lottie JSON animations
│  ├─ animation_1.json
│  └─ animation_2.json
├─ i/                     # Optional: Directory for image assets
│  ├─ img_1.webp
│  └─ img_2.png
├─ s/                     # Optional: Directory for state machine files
│  ├─ state_machine_1.json
│  └─ state_machine_2.json
├─ t/                     # Optional: Directory for theme files
│  ├─ theme_1.json
│  └─ theme_2.json
└─ f/                     # Optional: Directory for font assets
   ├─ BrandFont-Bold.ttf
   └─ BrandFont-Regular.woff2

manifest.json: Required JSON file at the root providing metadata and configuration.
a/: Required folder containing one or more Lottie JSON animation files.
i/: Optional folder for Lottie image assets referenced by the animations.
t/: Optional folder for theme files.
s/: Optional folder for state machine files.
f/: Optional folder for font assets referenced by themes.

Manifest Schema

The manifest.json file is placed at the root of the dotLottie archive and serves as the backbone of the format.

Properties

Field	Required	Type	Description
`version`	Yes	String	The version of the dotLottie spec. Must be `"2"` for v2 files.
`generator`	No	String	Name and version of the tool that generated the dotLottie file.
`animations`	Yes	Animation[]	An array containing metadata for each animation in the archive.
`themes`	No	Theme[]	An array of metadata for each theme asset in the archive.
`stateMachines`	No	StateMachine[]	An array of metadata for each state machine asset in the archive.
`initial`	No	Initial	Specifies which asset to load first.

Initial

Field	Required	Type	Description
`stateMachine`	No	String	The ID of the state machine to load initially, corresponding to a file in the `s/` directory.
`animation`	No	String	The ID of the animation to load initially, corresponding to a file in the `a/` directory.

Note: Players shall load the first animation by default if no initial animation or state machine is specified.

Animation

Field	Required	Type	Description
`id`	Yes	String	Unique identifier for the animation, corresponding to a file in the `a/` directory (e.g., `a/animation_01.json`).
`initialTheme`	No	String	ID of the theme to apply initially, corresponding to a file in the `t/` directory.
`background`	No	String (hex color)	Background color for the animation, represented as a hexadecimal string (e.g., `#FFFFFF`).
`themes`	No	Array<String>	Array of theme IDs scoped to this animation, each corresponding to a file in the `t/` directory.

Theme

Field	Required	Type	Description
`id`	Yes	String	Unique identifier for the theme, corresponding to a file in the `t/` directory.
`name`	No	String	A descriptive name for the theme.

State Machine

Field	Required	Type	Description
`id`	Yes	String	Unique identifier for the state machine, corresponding to a file in the `s/` directory.
`name`	No	String	A descriptive name for the state machine.

Manifest Example

{
  "version": "2",
  "generator": "dotLottie-cli@v2.0",
  "initial": {
    "animation": "animation_02"
  },
  "animations": [
    {
      "id": "animation_01"
    },
    {
      "id": "animation_02",
      "initialTheme": "theme_01",
      "background": "#F5F5F5"
    }
  ],
  "themes": [
    {
      "id": "theme_01",
      "name": "Light Theme"
    },
    {
      "id": "theme_02",
      "name": "Dark Theme"
    }
  ],
  "stateMachines": [
    {
      "id": "state_machine_01",
      "name": "Button States"
    }
  ]
}

Manifest JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "dotLottie Manifest",
  "type": "object",
  "required": ["version", "animations"],
  "properties": {
    "version": {
      "type": "string",
      "const": "2",
      "description": "Version of the dotLottie manifest"
    },
    "generator": {
      "type": "string",
      "description": "Tool or software used to generate the dotLottie file"
    },
    "animations": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9._ -]+$"
          },
          "initialTheme": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9._ -]+$"
          },
          "background": {
            "type": "string",
            "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
          },
          "themes": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9._ -]+$"
            }
          }
        },
        "additionalProperties": false
      }
    },
    "themes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9._ -]+$"
          },
          "name": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "stateMachines": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9._ -]+$"
          },
          "name": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "initial": {
      "type": "object",
      "properties": {
        "animation": { "type": "string" },
        "stateMachine": { "type": "string" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Animations

Animations are Lottie JSON files stored in the a/ directory at the root of the archive.

A valid dotLottie file must contain at least one Lottie animation.
Animation filenames must be POSIX-compliant: only alphanumeric characters, dots, underscores, spaces, and hyphens (^[a-zA-Z0-9._\- ]+$).
Each animation file must conform to the Lottie JSON specification.

The id in the manifest animations array must match the filename (excluding .json). For example, "id": "loading_spinner" references a/loading_spinner.json.

Assets

dotLottie packages assets together with animations in dedicated directories:

Asset Type	Directory	Supported Formats
Images	`i/`	PNG, JPG, WebP, SVG, GIF
Fonts	`f/`	TTF, OTF, WOFF, WOFF2

Assets can be referenced from Lottie animation files in several ways:

Path reference: Relative path from the archive root (e.g., i/logo.png)
Data URI: Assets embedded directly in the animation as Base64-encoded data
URL: Assets loaded from external sources via URL

Extracting assets into the i/ and f/ directories (rather than inlining as Data URIs) is recommended because it allows multiple animations to share assets and reduces overall file size.

Image Asset Reference Example

In a/animation_1.json:

{
  "assets": [
    {
      "id": "img_1",
      "p": "i/img_1.webp",
      "u": "",
      "e": 0
    }
  ]
}

Themes

Themes are optional JSON files stored in the t/ directory. Each theme defines how to override animated property values in a Lottie animation using a rules-based system.

A dotLottie theme is made up of rules that map to Lottie Slots. Only properties that have been assigned a slot ID in the Lottie animation can be targeted by theme rules.

For the complete theme file specification, see Theme Specification.

Theme System Behavior

SetTheme actions require the theme to exist in the manifest and be compatible with the current animation
Dynamic theme loading and theme inheritance are not supported
Theme changes apply to the renderer immediately; unknown themes are rejected during validation

Theme File Format

A theme file is a JSON object with a rules array:

{
  "rules": [
    {
      "id": "background_color",
      "type": "Color",
      "value": [0.12, 0.12, 0.12]
    },
    {
      "id": "icon_opacity",
      "type": "Scalar",
      "value": 80
    }
  ]
}

Supported Rule Types

Type	Overrides	Value Format
`Color`	Fill color, stroke color, text color	`[R, G, B]` (normalized 0–1 per channel)
`Scalar`	Opacity, stroke width, rotation, and other single values	Number
`Position`	Position, anchor point, gradient start/end	`[x, y]` or `[x, y, z]`
`Vector`	Scale, size	`[x, y]`
`Gradient`	Gradient color stops	Array of `{ color: [R,G,B], offset: number }`
`Image`	Image asset	`{ id, width, height, url }`
`Text`	Text document properties	Object with text, font, size, etc.

Rules can also use keyframes instead of a static value for animated overrides, and an optional expression field for dynamic Lottie expression-based values.

State Machines

State machines are optional JSON files stored in the s/ directory. They define interactive behaviors for animations.

For the complete state machine specification, see State Machine Specification.

Compression

A dotLottie file is a ZIP archive compressed using the Deflate method.

Optimization Recommendations

JSON Minification: Remove whitespace from JSON files before packaging
Image Compression: Use WebP or compressed PNGs to reduce size
Asset Deduplication: Share assets across animations to avoid duplication
Short directory names: The a/, i/, s/, t/, f/ naming in v2 reduces path overhead

Creating a .lottie File

# Build the directory structure
mkdir -p my-animation/{a,i,t,s}
cp animation.json my-animation/a/
cp logo.webp my-animation/i/
cp theme_light.json my-animation/t/

# Write manifest.json
cat > my-animation/manifest.json << 'EOF'
{
  "version": "2",
  "animations": [{ "id": "animation" }]
}
EOF

# Package as .lottie
cd my-animation && zip -r ../my-animation.lottie .

Extracting a .lottie File

# Extract
unzip animation.lottie -d extracted/

# View manifest
cat extracted/manifest.json

# Extract specific animation
unzip -p animation.lottie a/main.json > animation.json

Manifest Validation Rules

manifest.json must exist at the archive root
Manifest must be valid JSON with version and animations fields
version must be "2" for v2 files
animations array must contain at least one entry
All animation id values must be unique
Each animation id must match a corresponding file in a/ (e.g., id: "foo" → a/foo.json)

Complete Examples

Example 1: Simple Single Animation

manifest.json

{
  "version": "2",
  "generator": "LottieFiles Plugin 3.0",
  "animations": [
    {
      "id": "main_animation"
    }
  ]
}

Archive structure

simple.lottie
├── manifest.json
└── a/
    └── main_animation.json

Example 2: Multi-Animation with Assets

manifest.json

{
  "version": "2",
  "generator": "Custom Tool 1.0",
  "animations": [
    {
      "id": "loading"
    },
    {
      "id": "success"
    },
    {
      "id": "error"
    }
  ]
}

Archive structure

multi.lottie
├── manifest.json
├── a/
│   ├── loading.json
│   ├── success.json
│   └── error.json
└── i/
    ├── checkmark.png
    └── error-icon.png

Example 3: Themed Interactive Animation

manifest.json

{
  "version": "2",
  "generator": "dotLottie Builder 2.0",
  "initial": {
    "stateMachine": "button-interaction"
  },
  "animations": [
    {
      "id": "button",
      "initialTheme": "light",
      "themes": ["light", "dark", "high_contrast"]
    }
  ],
  "themes": [
    { "id": "light", "name": "Light" },
    { "id": "dark", "name": "Dark" },
    { "id": "high_contrast", "name": "High Contrast" }
  ],
  "stateMachines": [
    { "id": "button-interaction", "name": "Button States" }
  ]
}

Archive structure

interactive.lottie
├── manifest.json
├── a/
│   └── button.json
├── t/
│   ├── light.json
│   ├── dark.json
│   └── high_contrast.json
└── s/
    └── button-interaction.json

v1.0 (Legacy)

dotLottie v1.0 files use a different directory structure and manifest schema. v1.0 is considered legacy and new files should use v2.

Key differences from v2:

Aspect	v1.0	v2
Animations dir	`animations/`	`a/`
Images dir	`images/`	`i/`
Themes dir	Not supported	`t/`
State machines dir	Not supported	`s/`
Fonts dir	Not supported	`f/`
Manifest version	`"1"`	`"2"`
Animation object	Includes playback controls (autoplay, loop, speed, direction, etc.)	Only `id`, `initialTheme`, `background`, `themes`
Multi-animation	Via `activeAnimationId`	Via `initial.animation`
Theming	Not supported	Rules-based via `t/` directory
State machines	Not supported	Via `s/` directory

Best Practices

Use descriptive, unique IDs for all animations, themes, and state machines
Extract image assets to i/ rather than inlining as Data URIs
Minify JSON files before packaging to reduce file size
Validate the manifest against the JSON Schema before distribution
Specify an initial entry when the dotLottie contains multiple animations or a state machine