The Lottie file (.json, .lottie)

A Lottie file describes an animation the way a design tool does: shapes, colours, layers and how each property changes over time. A player reads the description and draws every frame live, as vector graphics. The result is sharp at any size, usually small, and can be controlled from code: played, paused, looped, slowed down or jumped to a frame.

The format began in 2015 with Bodymovin, an After Effects extension by Hernan Torrisi that exported animations to JSON along with a JavaScript player for the web. In 2017 Airbnb engineers Brandon Withrow, Gabriel Peal and Leland Richardson, with motion designer Salih Abdul-Karim, built libraries to play those files natively on iOS and Android, and later React Native, and named the project Lottie. It became a common way to ship interface animations: loading spinners, success ticks, onboarding illustrations, animated icons.

For years the format was defined only by what Bodymovin wrote and what the players read. In 2023 the Lottie Animation Community formed under the Joint Development Foundation, a Linux Foundation project, to turn it into a standard. It published the Lottie Specification 1.0 on 17 September 2024, and in February 2025 IANA registered the media type video/lottie+json, with .lot as an optional extension. Most files still end in .json.

Three things a Lottie file is not:

• Not a video. There are no frames inside, only instructions. Nothing plays it without a Lottie player.
• Not just any JSON file. A .json file is a Lottie animation only if it has this structure. Check for "v", "fr", "layers" near the top.
• Not a complete copy of After Effects. Players support a large part of what After Effects can do, but effects, some layer types and expressions are supported unevenly. Test an animation in the player you'll use.

A .lottie file is a dotLottie package, a format created and specified by LottieFiles: a ZIP archive, compressed with Deflate, that holds one or more Lottie JSON animations together with their images, fonts, themes and interactivity. It's not JSON, so a text editor shows binary; rename a copy to .zip to look inside.

manifest.json      required: version "2", the animations, themes
                   and state machines it contains
a/                 required: the Lottie JSON animations, at least one
i/                 images used by the animations
f/                 fonts
t/                 themes: alternative colours, e.g. light and dark
s/                 state machines: what happens on click, hover…

• Smaller downloads. The JSON is compressed and images are stored as files instead of base64 text. LottieFiles says dotLottie files are often up to 80% smaller than the equivalent JSON; how much you save depends on the animation.
• Several animations in one file, sharing images and fonts, with one marked as the one to start with.
• Themes and state machines: a dotLottie 2 file can switch colours at runtime and react to clicks, hovers and scrolling without extra code.
• Versions: dotLottie 1 used folders named animations/ and images/; version 2 uses the short names above. Check which versions your player reads.

Not every player reads .lottie files: Airbnb's lottie-web plays only JSON. LottieFiles' dotLottie players (for the web, React, Vue, Svelte, React Native, Flutter, Android and iOS) play both.

With lottie-web, Airbnb's JavaScript player, a few lines play an animation from a URL:

<div id="anim" style="width: 200px; height: 200px"></div>
<script src="lottie.min.js"></script>
<script>
  lottie.loadAnimation({
    container: document.getElementById("anim"),
    renderer: "svg",      // or "canvas", "html"
    loop: true,
    autoplay: true,
    path: "dot.json"      // or animationData: a parsed object
  });
</script>

• Renderers: lottie-web draws with SVG, canvas or HTML elements. Which is fastest depends on the animation, so try more than one if playback stutters.
• Loading from another site needs that site to allow it with CORS headers, because the player fetches the JSON with JavaScript. Keeping the page and the animation on the same site avoids the problem.
• For .lottie files, use a dotLottie player instead, such as @lottiefiles/dotlottie-web or its web component.
• In apps: Airbnb's Lottie libraries for Android, iOS and React Native, or the dotLottie players, which also cover Flutter.

To preview a file without writing code, drop it on the free LottieFiles previewer, which takes JSON and dotLottie files up to 20 MB, or use the LottieFiles extension for VS Code, which refreshes the preview as you edit the JSON. To edit it, go back to the source in After Effects, or use an editor that imports Lottie; editing the JSON by hand works for small changes such as colours or speed.

Lottie's strength is designer-made vector animation that stays small and crisp and can be driven by the interface. For photographic or very detailed motion, a WebM or MP4 video is smaller and cheaper to play. For a loop that must work without JavaScript, such as in email, a GIF is still the safe choice.

• A small file can be slow. The player redraws every frame. Many layers, masks and mattes (which lottie-web's documentation calls out as costly), blur-like effects and long paths use a lot of CPU, especially on phones. Simplify in After Effects, or try the canvas renderer.
• The file is huge. Usually embedded images: raster pictures stored as base64 text inside the JSON. Export images as separate files, compress them, or use dotLottie, which stores them as files in the ZIP.
• It looks different from After Effects. The player doesn't support something in it: some effects, layer styles, expressions, or text features. lottie-web, for example, doesn't play image sequences, video or audio layers. Check the exporter's warnings, and test in the target player.
• Text renders in the wrong font. Text layers need their fonts to be available to the player, or the text converted to shapes before export.
• Nothing appears. Check the browser console: a CORS error, a 404 for the JSON, or a container element with no height are the usual causes.

Plain Lottie JSON is data, as safe as any JSON file. IANA's registration says its security considerations are like those of JSON, with two additions worth knowing:

• Expressions can run code. After Effects expressions are JavaScript snippets, and an optional Lottie extension carries them in the file. IANA notes that this can enable code execution, depending on the player. lottie-web's full build evaluates expressions with JavaScript's eval, which also means it needs unsafe-eval under a strict Content Security Policy; the lottie_light builds in the same package contain no eval at all. Expressions are not part of the Lottie Specification 1.0.
• External assets. An animation can reference images by URL, so playing it makes the browser request them. Treat animations from untrusted sources like any third-party content.
• Resource exhaustion. A crafted file with huge dimensions, thousands of layers or extreme frame counts can freeze a page or app. Don't autoplay user-uploaded animations without limits.
• dotLottie is a ZIP, so a server that unpacks uploaded .lottie files inherits ZIP risks such as archive bombs and file names with ../ in them. Check sizes and paths.