If you’ve downloaded or exported a Lottie animation, you’ve probably encountered two file formats: .json and .lottie.
Both formats are used to deliver Lottie animations to websites, mobile applications, and digital products. However, they differ in how animation data, assets, and other resources are stored and delivered.
The main difference is that Lottie JSON stores animation data in a readable JSON file, while .lottie packages one or more Lottie animations and their associated resources into a compressed archive.
So, which format should you use?
The answer depends on your project, your animation player, and whether you need a simple animation file or a more comprehensive animation package.
In this guide, we’ll compare Lottie JSON vs .lottie, explain how each format works, and help you choose the right option for your website, app, or interactive UI.
Quick Answer: Lottie JSON vs .lottie
If you’re looking for a quick comparison, here’s what you need to know.
| Feature | Lottie JSON (.json) | dotLottie (.lottie) |
|---|---|---|
| File type | JSON document | Compressed archive |
| Main purpose | Store animation data | Package animations and resources |
| Human-readable | Yes | Not directly |
| Multiple animations | Typically one animation per file | Can contain multiple animations |
| Image assets | May be embedded or referenced externally | Can package associated assets |
| Compression | Depends on delivery and optimization | Uses archive compression |
| Themes | Not a standard package-level feature | Supported in dotLottie v2 |
| State machines | Requires separate implementation or tooling | Supported in dotLottie v2 |
| File management | Separate files may be needed | Related resources can be bundled |
| Compatibility | Supported by compatible Lottie players | Requires a compatible dotLottie player |
In short: Use JSON when you need direct access to animation data and a straightforward integration. Consider .lottie when you want to package multiple animations, shared assets, themes, or interactive state machines.
Compatibility depends on the player, format version, and features used.
What Is Lottie JSON?
Lottie JSON is a file format used to describe animations as structured JSON data.
A typical Lottie JSON file contains information about the animation’s layers, shapes, transforms, keyframes, timing, and other properties needed to render the animation.
Instead of storing an animation as a video, Lottie describes how its visual elements should move and change over time.
This allows compatible players to render the animation at different sizes without relying on a fixed-resolution video.
What Does a Lottie JSON File Contain?
A Lottie JSON file can include:
- Layers: Organize the individual elements of an animation.
- Shapes: Define vector-based visual elements.
- Transformations: Control position, rotation, scale, and opacity.
- Keyframes: Define how properties change over time.
- Timing: Specify the animation’s frame rate, duration, and playback range.
- Masks and effects: Describe supported visual effects and compositing behavior.
- Assets: Reference or embed resources such as images.
- Metadata: Store information about the animation.
The exact properties depend on how the animation was created and which Lottie features it uses.
Example of a Lottie JSON File
A simplified Lottie JSON file might look like this:
{
"v": "5.12.0",
"fr": 30,
"ip": 0,
"op": 60,
"w": 500,
"h": 500,
"nm": "Loading Animation",
"ddd": 0,
"assets": [],
"layers": []
}This example illustrates some common animation metadata:
fr: Frame rate.ip: Starting frame.op: Ending frame.wandh: Animation dimensions.nm: Animation name.layers: The elements used to build the animation.
This is a simplified illustration, not a complete production-ready animation.
Advantages of Lottie JSON
Lottie JSON is useful when you need:
- Easy inspection: Open the file in a text editor to inspect its structure.
- Direct access to animation data: Modify supported properties programmatically.
- Straightforward integration: Use compatible players that accept JSON animation data.
- Simple debugging: Inspect layers, timing, and other animation properties.
- Existing workflow compatibility: Continue using established JSON-based pipelines.
Limitations of Lottie JSON
JSON also has some limitations:
- Related image assets may need to be managed separately.
- Multiple animations are commonly distributed as separate files.
- Large animations can produce sizable JSON files.
- Advanced interactive behavior may require additional code or supporting resources.
- A JSON file does not automatically provide the package-level features of dotLottie.
What Is a .lottie File?
A .lottie file is a packaged format designed specifically for Lottie animations.
The format, commonly known as dotLottie, stores Lottie animation data and associated resources inside a compressed archive.
A .lottie file is structured as a ZIP-based package with a defined internal layout. Depending on its specification version and contents, it can include animation JSON files, images, metadata, themes, fonts, and state machine definitions.
This approach helps keep related animation resources together instead of requiring developers to manage multiple separate files.
What Does a .lottie File Contain?
A dotLottie package can include:
- One or more Lottie JSON animations.
- Image assets used by the animations.
- A manifest containing package metadata.
- Themes for supported animation properties.
- State machine definitions for interactive behavior.
- Supporting font resources in compatible format versions.
Not every .lottie file contains all these elements. The contents depend on the package and the specification version used.
How Is a .lottie File Structured?
A simplified dotLottie v2 package may contain a structure like this:
animation.lottie
│
├── manifest.json
├── a/
│ ├── loading.json
│ └── success.json
├── i/
│ └── illustration.webp
├── t/
│ └── dark-theme.json
└── s/
└── interaction.jsonHere’s what these components represent:
| Component | Purpose |
|---|---|
manifest.json | Describes the package and its contents |
a/ | Stores animation JSON files |
i/ | Stores image assets |
t/ | Stores theme definitions |
s/ | Stores state machine definitions |
This is an illustrative structure for dotLottie v2. The internal directory names differ between format versions.
Advantages of .lottie
The dotLottie format offers several capabilities:
- Bundled resources: Keep related animations and assets together.
- Multiple animations: Package several animations in a single file.
- Compression: Use archive compression to reduce the size of packaged data.
- Shared assets: Reuse assets across animations when the package is structured accordingly.
- Theming: Apply supported property overrides through theme definitions.
- Interactive behavior: Use state machines to coordinate animation states and transitions.
- Simplified distribution: Deliver related animation resources as one package.
Limitations of .lottie
There are also practical considerations:
- A
.lottiefile is not directly readable as plain text. - You need a compatible dotLottie player or tool to work with the package.
- Older players may not support newer format features.
- Extracting and editing individual animations may require additional tools.
- A compressed package is not guaranteed to be smaller than every equivalent JSON file.
Lottie JSON vs .lottie: Key Differences Explained
Let’s examine the main differences in more detail.
1. File Structure and Storage
The biggest difference between JSON and .lottie is how they organize animation data.
A JSON file contains the animation’s structured data directly.
A .lottie file packages animation JSON files and other resources in a defined archive.
For example, if you’re using five separate loading animations, you might distribute five JSON files. With dotLottie, those animations can be packaged together in a single .lottie file.
This can simplify asset organization, especially in applications with multiple related animations.
2. File Size and Compression
File size is an important consideration when using animations on websites and mobile applications.
A .lottie file uses archive compression, which can reduce the size of its packaged contents.
However, the actual size difference depends on several factors:
- The complexity of the animation.
- The amount of repeated data.
- Whether image assets are embedded or stored separately.
- Whether the JSON file is already minified or compressed for delivery.
- Whether multiple animations share assets.
- The compression settings used during packaging.
A .lottie file is not automatically smaller than every JSON file.
For a single, simple animation, the size difference may be small. For a package containing multiple animations and shared assets, packaging can provide more substantial benefits.
If you’re optimizing an existing JSON file, try the Lottie Wizard – Lottie Compressor to explore ways to reduce its size before implementation.
3. Multiple Animations in One File
A standard JSON animation file typically represents one animation.
A dotLottie package can contain multiple animations that can be selected by a compatible player.
Imagine a UI component with the following states:
- Idle
- Loading
- Success
- Error
You could manage these as separate JSON files or package them together in a .lottie file.
The packaged approach can help keep related animations organized and make them easier to distribute as a single resource.
4. Image Assets and Resource Management
Lottie animations sometimes rely on images in addition to vector shapes.
With JSON, these assets may be embedded directly in the animation data or referenced through external resources.
With dotLottie, compatible packages can store image assets alongside the animation files.
This can make it easier to manage animations that depend on several related resources.
However, asset packaging alone does not guarantee better performance. The final result depends on asset sizes, compression, caching, and how the player loads resources.
5. Developer Experience and Debugging
JSON is generally easier to inspect and troubleshoot because its contents are readable as text.
You can open a JSON file in a text editor and examine the animation’s properties.
A .lottie package requires a compatible tool or archive extraction process to inspect its internal files.
However, packaging can simplify project organization when you’re managing multiple animations and associated resources.
The right choice depends on whether your workflow prioritizes direct access to animation data or packaged asset management.
When Should You Use Lottie JSON?
Lottie JSON is a practical choice for many existing web and mobile animation workflows.
Consider using JSON when:
You’re Adding a Simple Animation to a Website
If you need a loading spinner, animated icon, success indicator, or small illustration, a JSON file may be all you need.
It can be integrated into a compatible player without requiring a multi-animation package.
You Need to Inspect or Modify Animation Data
JSON is useful when you’re debugging an animation or programmatically modifying supported properties.
Its readable structure makes it easier to investigate how an animation is built.
You’re Working With an Existing JSON-Based Application
If your application already uses a Lottie player that expects JSON, continuing with JSON may be the most straightforward option.
You can evaluate a move to dotLottie separately, based on your feature and compatibility requirements.
You Want to Share a Single Animation
When you only need to distribute one animation, a standalone JSON file can be convenient, particularly when the animation does not depend on separate image resources.
When Should You Use .lottie?
dotLottie becomes particularly useful when you need more than a standalone animation file.
Consider using .lottie when:
You’re Managing Multiple Related Animations
For applications with several related animation states, a single package can keep the animation files organized together.
This is useful for UI components, icon collections, and product animation systems.
You Need to Bundle Animation Assets
If your animations depend on images or other supported resources, packaging them together can simplify distribution.
You’re Building Interactive UI Components
If your application uses supported themes or state machines, dotLottie v2 can help organize those features within a single package.
Examples include:
- Animated buttons.
- Interactive toggles.
- Multi-state loading indicators.
- Interactive illustrations.
- Product onboarding animations.
You’re Building a Reusable Animation System
For design systems and applications that reuse animations across multiple components, packaging can help organize shared resources and related animation states.
The exact benefits depend on how the package is designed and how the player loads its contents.
Can You Convert Lottie JSON to .lottie?
Yes. A compatible tool can package a Lottie JSON animation into a .lottie file.
The conversion process generally involves:
- Loading the original JSON animation.
- Checking whether the animation uses external assets.
- Packaging the animation and any required resources.
- Generating the package manifest.
- Saving the result as a
.lottiefile. - Testing the package in a compatible player.
Keep in mind that converting a JSON file to .lottie does not automatically add themes, state machines, or new animation features.
Those features require additional configuration and compatible animation data.
Can You Convert .lottie Back to JSON?
Yes. Because a dotLottie package contains Lottie JSON animation data, a compatible tool can extract the animation files.
If the package contains multiple animations, you may need to select the specific animation you want to extract.
You may also need to extract associated image assets and other resources to reproduce the original animation correctly.
How to Preview and Validate Lottie JSON and .lottie Files
Before integrating an animation into a website or application, preview it to make sure it works as expected.
A simple validation workflow can help identify issues with playback, assets, and compatibility.
Step 1: Upload Your Animation
Open the Lottie Wizard Online Viewer and use the available viewer to inspect your animation.
Step 2: Preview the Animation
Check the animation’s appearance, timing, and playback.
Look for missing images, unexpected behavior, or rendering differences.
Step 3: Check Compatibility
Confirm that your intended player supports the file format and the features used by the animation.
This is particularly important when working with dotLottie packages that use newer features.
Step 4: Optimize the File
If the animation is too large, consider optimizing the JSON data or compressing image assets.
You can explore the Lottie Wizard Lottie Compressor as part of your optimization workflow.
Step 5: Test It in Your Application
Previewing an animation in a viewer is useful, but it does not replace testing it in your actual website or application.
Verify that the animation loads and plays correctly in the target environment.
Recommended workflow:
Upload → Preview → Validate → Optimize → Implement
What About React and Other Frameworks?
Both Lottie JSON and dotLottie can be used in modern web and mobile applications, provided the chosen player supports the format.
The integration method depends on the framework and animation player.
For example, a React application may use a player that accepts JSON animation data or a dotLottie-compatible player.
Before choosing a format, verify:
- Whether the player supports
.json,.lottie, or both. - Which dotLottie specification versions are supported.
- Whether the player supports the features your animation requires.
- How assets are loaded and cached.
- Whether the player works with your target browsers and devices.
If you’re developing a React application, continue with our guide:
How to Add Lottie Animation to React
Frequently Asked Questions
1. What is the difference between Lottie JSON and .lottie?
Lottie JSON is a readable JSON document that describes an animation. A .lottie file is a compressed package that can contain one or more Lottie animations and associated resources.
2. Is .lottie better than JSON?
Neither format is universally better. JSON is useful for standalone animations and direct access to animation data, while .lottie is useful for packaging multiple animations, assets, and supported advanced features.
3. Is a .lottie file smaller than JSON?
A .lottie file uses archive compression, which can reduce file size. However, the actual difference depends on the animation, its assets, and whether the original JSON is already optimized or compressed.
4. Can a .lottie file contain multiple animations?
Yes. A dotLottie package can contain multiple Lottie animations, which can be selected by a compatible player.
5. Can I open a .lottie file in a text editor?
Not directly. A .lottie file is a compressed archive. You need a compatible tool or archive extraction process to inspect its contents.
6. Can I use .lottie files in React?
Yes, if you use a React-compatible player that supports the relevant dotLottie format version and features.
7. Can I convert JSON to .lottie?
Yes. Compatible tools can package JSON animation data into a .lottie file. Any required image assets and package metadata must also be handled correctly.
8. Is dotLottie replacing Lottie JSON?
No. JSON remains widely used in existing Lottie workflows. dotLottie provides a packaged format with additional capabilities, and both formats remain relevant depending on the project.
9. Does .lottie support themes and state machines?
The dotLottie v2 specification supports themes and state machines. Actual functionality depends on the package contents and player compatibility.
10. Which format should I use for website animations?
For a simple website animation, JSON may be sufficient. If you need multiple animations, bundled assets, or supported advanced features, consider .lottie.
How to Choose Between Lottie JSON and .lottie?
Lottie JSON and dotLottie serve related but different purposes.
JSON provides direct access to animation data and works well for many standalone animation workflows.
dotLottie provides a structured way to package animations, assets, and additional resources together, with support for features such as themes and state machines in its v2 specification.
Before choosing a format, consider your animation’s complexity, the resources it requires, and the capabilities of your intended player.
Explore more Lottie resources on LottieWizard:
- Lottie Wizard Online Viewer
- Lottie Animation Integration Guide
- Lottie To Mp4 Converter
- Lottie To Gif Converter
- Lottie Json Compressor Tool
Preview your animation, validate its compatibility, optimize its size, and choose the format that fits your project.
The technical explanations in this article are based on the official dotLottie format documentation and Lottie specification.
