Lottie Animation Format

Welcome to the official documentation for Lottie, a JSON-based format for animated vector graphics.

This manual contains formal specification and documentation for the Lottie file format, offering insights into its structure and features.

The main target audience for this manual are developers that want to create tools within the Lottie ecosystem as it provides details about the JSON internals.

Status of this manual

The Lottie specification is still a work in progress, this document contains a subset of features that have been approved by the Lottie Animation Community. The documentation and specs will be expanded as more of the Lottie format becomes standardized.

Once the draft is complete, there will be an announcement by the Lottie Animation Community.

Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Document Structure

Lottie documents MUST use JSON [RFC8259] to structure their data. The top-level object in a Lottie document MUST be an Animation object.

Implementation MAY store additional data in the JSON objects.

A machine-readable specification of the JSON structure is available as JSON Schema.

Where to start

Since Lottie uses JSON, basic JSON knowledge is required to understand the specification.

To understand Lottie data, it's useful to start learning about basic values and animated properties.

The root object of any Lottie animation is the Animation object.

A printable single-page version of the specification is available here.

Values

Integer Boolean

Represents boolean values as an integer. `0` is false, `1` is true.

Vector

Vector data is represented by an array of numbers. This is used any time a property with multiple components is needed.

An example would be a position, which would be represented as an array with two numbers, the first corresponding to the X coordinate and the second corresponding to the Y.

Color

Colors are Vectors with values between 0 and 1 for the RGB components.

For example:

• [1, 0, 0]
• [1, 0.5, 0]

Note: sometimes you might find color values with 4 components (the 4th being alpha) but most players ignore the last component.

Hex Color

Colors represented as a "#"-prefixed string, with two hexadecimal digits per RGB component.

• #FF8000

Gradient

The gradient appearance is specified in terms of color stops and opacity stops. Color stops are defined as (position, color) tuples, where the position is a normalized [0..1]value along the gradient axis [startpoint -> endpoint], and the color is 3 floats representing the RGB components. Transparency (opacity) stops are defined as (position, color) tuples, where position is similar to color stops' position.

All color and opacity stops are stored sequentially by ascending offsets in a flattened float array (color stops followed by opacity stops), with 4 floats per color stop and 2 floats per opacity stops. Thus, given color stops and opacity stops, the expected size for the gradient data array is 4 * Nc + 2 * No.

The color stop count is typically specified in a separate field from the gradient values, while the count of opacity stops can be inferred from the data array length: No = (length - 4 * Nc)/2.

Gradient without transparency

So let's say you want these colors:

• [0.16, 0.18, 0.46]
• [0.2, 0.31, 0.69]
• [0.77, 0.85, 0.96]

the array will look like the following:

[0, 0.16, 0.18, 0.46, 0.5, 0.2, 0.31, 0.69, 1, 0.77, 0.85, 0.96]

Gradient with transparency

Transparency stops are added at the end. Transparency stops may or may not match the count and offset of color stops.

So assume the same colors as before, but opacity of 80% for the first color and 100% for the other two.

The array will look like this:

[0, 0.16, 0.18, 0.46, 0.5, 0.2, 0.31, 0.69, 1, 0.77, 0.85, 0.96, 0, 0.8, 0.5, 0.2, 1, 1]

It's the same array as the case without transparency but with the following values added at the end:

Gradient Example

Bezier Shape

Cubic polybezier

Data URL

Data URLs are embedded files (such as images) as defined in [RFC2397].

Properties

Introduction

Properties in Lottie can be animated.

Their structure depends on whether it's animated or not:

Keyframes

Keyframe arrays MUST be stored in order of ascending t frame number.

Two consecutive keyframes MAY have the same t value but a property MUST NOT have more than two keyframes with the same t. If two keyframes share the t value, the implementation MUST render one of the two values at the given frame.

All keyframes MUST have an i and o value, unless-

• It is the last keyframe in the sequence OR
• h is present and it's 1, as the property will keep the same value until the next keyframe.

If the first keyframe occurs after the start of the animation, the initial property value will be from the first keyframe. Similarly, if the last keyframe is before the end of the animation, the last keyframe value will be held until the end.

Keyframe Easing

Keyframe easing handles are objects with x and y attributes, which are numbers within 0 and 1.

For vector properties, these are arrays, with one element per dimension so you can have different easing curves per dimension.

They represent a cubic bezier, starting at [0,0] and ending at [1,1] where the value determines the easing function.

The x axis represents time, a value of 0 is the time of the current keyframe, a value of 1 is the time of the next keyframe.

The y axis represents the value interpolation factor, a value of 0 represents the value at the current keyframe, a value of 1 represents the value at the next keyframe.

Unlike x values, y values are not clamped to [0 .. 1]. Supernormal y values allow the interpolated value to overshoot (extrapolate) beyond the specified keyframe values range.

When you use easing you have two easing handles for the keyframe:

o is the "out" handle, and is the first one in the bezier, determines the curve as it exits the current keyframe.

i is the "in" handle, and it's the second one in the bezier, determines the curve as it enters the next keyframe.

For linear interpolation you'd have

{
    "o": {"x": [0, 0], "y": [0, 0]},
    "i": {"x": [1, 1], "y": [1, 1]}
}

For easing in and out, you move the x towards the center, this makes the animation more fluid:

{
    "o": {"x": [0.333, 0.333], "y": [0, 0]},
    "i": {"x": [0.667, 0.667], "y": [1, 1]}
}

Easing example

In the following example, the ball moves left and right, on the background you can see and edit a representation of its easing function.

Property types

Vector

Animatable Vector.

Vector Keyframe

Scalar

Animatable scalar (single number value).

Note that when animated it uses Vector Keyframes, so instead of scalars keyframes have arrays with a single values.

Position

Animatable 2D Vector with optional spatial tangents.

Position Keyframe

Split Position

An animatable position where position values may be defined and animated separately.

Bezier Shape

Animatable Bezier.

Bezier Shape Keyframe

Color

Animatable Color.

Color Keyframe

Gradient

Animatable Gradient.

Color count is not animatable.

Gradient Keyframe

Composition

Animation

Top level object, describing the animation

Versioning Guidelines

The Lottie specification version number uses a semantic versioning system, tools implementing the specification SHOULD consider the following guidelines:

• Major version signal the possibility of breaking changes that are not compatible with previous versions of the specification.
• Minor version updates typically add new functionality but do not contain breaking changes for existing features.
• Patch version updates typically make minor changes or clarifications to already existing functionality.

Authoring Tools

Authoring tools SHOULD specify the latest version of the Lottie Specification. They MAY allow the major version to be configurable to facilitate playback on a wider range of players. Changing the targeted major version MAY also require changes to the produced animation in the case of any breaking changes between major versions.

Animation Players

Players SHOULD determine what major versions they support and handle breaking changes across supported major versions. Players SHOULD be able to handle animations that specify both newer and older versions of the Lottie specification and SHOULD issue a warning if:

• The animation specifies a major version that is not supported.
• The animation specifies a newer minor version.
• No warning needed if the specified patch version is different.

Composition

An object that contains a list of layers

Layers

Common Properties

Layer

Common properties for all layers

The ty property defines the specific layer type based on the following values:

Visual Layer

Layer used to affect visual elements

Parenting

Layer parenting offers a way to connect layers such that the movement of one layer (child) follows the movement of another (parent). Multiple child layers can reference the same parent (this is useful for applying the same transform animation to a group of layers).

When the parent property points to another layer, the referencing layer's current transformation matrix (CTM) is composed with the parent CTM:

Parenting is transitive, and reference cycles are not allowed (undefined behavior).

Hidden Layers

The hidden flag hd determines whether a layer is rendered: hidden layers are not rendered as part of the normal layer tree, but their properties and content are evaluated when used as a reference target in other contexts.

Specifically, hidden layers

• contribute to a layer's total transform when used as a parent
• contribute to a layer's track matte when used as a matte source

hd only affects the layer for which it is defined, it does not transitively apply to other referencing layers.

Mattes

A matte allows using a layer as a mask for another layer.

The way it works is the layer defining the mask has a tt attribute with the appropriate value. The layer being masked is indicated by the tp attribute, which has the index (ind) of the layer that is being masked.

In this example there's a layer with a rectangle and a star being masked by an ellipse:

Example

Layer types

Shape Layer

Layer containing Shapes

Image Layer

Layer containing an image

Null Layer

Layer with no data, useful to group layers together

Solid Layer

Solid color, rectangle-shaped layer

Precomposition Layer

Layer that renders a Precomposition asset

Time Stretch

The st property specifies a start time offset, while sr defines a time stretch factor, to be applied when evaluating animated properties pertaining to the layer:

sr values less than $1$ increase the layer playback speed, while values greater than $1$ decrease it ("stretching" the layer timeline).

Example

Time Remap

The tm property specifies a time remap function as an animatable property, allowing full control over the precomp timeline (subset, speedup/slowdown, reverse, frame-freeze, or any other arbitrary transformation).

It maps the current layer time (in the frame index $[ip\dots op]$ domain) to a precomp time expressed in seconds, and evaluates all animatable precomp properties based on the new time value:

Note: the global frame rate factor $FPS$ (Animation fr property) is required to convert back into the frame index domain.

When both time stretch (sr) and time remap (tm) are specified, time stretch is applied first.

Example

Shapes

The graphical elements are divided in 4 categories:

• Shapes that define the actual curves but have no styling information
• Grouping, used to organize collections of graphic elements
• Styles, that define the visual appearance of shapes
• Modifiers alter the curves of the shapes

Shape Rendering Model

Grouping and Ordering Rules

• Shapes are rendered in reverse order, bottom->top. Shapes at the beginning of the array are rendered on top of shapes with larger indices.
• Groups offer a scoping mechanism for transforms, styles, modifiers, and shapes. All group children, including sub-groups and their children, are considered part of the group's scope.
• Transforms adjust the coordinate system for all elements within their group, and transitively for all other group-nested elements.
• Styles and modifiers apply to all preceding shapes within the current scope, including subgroup-nested shapes.
• When multiple styles apply to the same shape, the shape is rendered repeatedly for each style, in reverse order.
• When multiple modifiers apply to the same shape, they are composed in reverse order (e.g. $Trim(Trim(shape))$).
• When multiple transforms apply to the same shape due to scope nesting, they compose in group nesting order (transforms are additive).
• Group opacity (property of the group transform) applies atomically to all elements in scope - i.e. opacity applies to the result of compositing all group content, and not to individual elements.

More formally:

• for each $(shape,style)$ tuple, where $Index(shape)<Index(style)$ and $shape\in Scope(style)$:
• for each $modifier$, in increasing index order, where $Index(shape)<Index(modifier)$ and $shape\in Scope(modifier)$:
  • $shape=modifier(shape)$
• compute the total shape transformation by composing all transforms within the shape scope chain:

• compute the total style transformation by composing all transforms within the style scope chain:

• $Render(shape\times T_{shape},style\times T_{style})$

Notes

1. Certain modifier operations (e.g. sequential $Trim$) may require information about shapes from different groups, thus $Render()$ calls cannot always be issued based on single-pass local knowledge.

2. Transforms can affect both shapes and styles (e.g. stroke width). For a given $(shape,style)$, the shape and style transforms are not necessarily equal.

3. Shapes without an applicable style are not rendered.

4. This rendering model is based on AfterEffects' Shape Layer semantics.

Rendering Convention

Shapes defined in this section contain rendering instructions. These instructions are used to generate the path as a bezier curve.

Implementations MAY use different algorithms or primitives to render the shapes but the result MUST be equivalent to the paths defined here.

Some instructions define named values for clarity and illustrative purposes, implementations are not required to have them explicitly defined in their rendering process.

When referencing animated properties, the rendering instruction will use the same name as in the JSON but it's assumed they refer to their value at a given point in time rather than the property itself. For Vector values, $value.x$ and $value.y$ in the instructions are equivalent to value[0] and value[1] respectively.

All paths MUST be closed unless specified otherwise in the rendering instructions.

When instructions call for an equality comparison between two values, implementations MAY consider similar values to be equal to overcome numerical instability.

Drawing Commands

Drawing instructions will contain the following commands:

• add vertex: Adds a vertex to the bezier shape in global coordinates
• set in tangent: Sets the cubic tangent to the last added vertex, with coordinates relative to it. If omitted, tangents MUST be $(0,0)$.
• set out tangent: Sets the cubic tangent from the last added vertex, with coordinates relative to it. If omitted, tangents MUST be $(0,0)$.
• lerp: Linearly interpolates two points or scalars by a given amount.

Approximating Ellipses with Cubic Bezier

An elliptical quadrant can be approximated by a cubic bezier segment with tangents of length $radius \cdot E_t.

Where

See this article for the math behind it.

When implementations render elliptical arcs using bezier curves, they SHOULD use this constant, a similar approximation, or elliptical arc drawing primitives.

Graphic Element

Element used to display vector data in a shape layer

The ty property defines the specific element type based on the following values:

Hidden shapes (hd: True) are ignored, and do not contribute to rendering nor modifier operations.

Shapes

Drawable shape, defines the actual shape but not the style

Ellipse

Ellipse shape

Example

An ellipse is drawn from the top quandrant point going clockwise:

1. Add vertex $(x,y-radius.y)$
2. Set in tangent $(-tangent.x,0)$
3. Set out tangent $(tangent.x,0)$
4. Add vertex $(x+radius.x,y)$
5. Set in tangent $(0,-tangent.y)$
6. Set out tangent $(0,tangent.y)$
7. Add vertex $(x,y+radius.y)$
8. Set in tangent $(tangent.x,0)$
9. Set out tangent $(-tangent.x,0)$
10. Add vertex $(x-radius.x,y)$
11. Set in tangent $(0,tangent.y)$
12. Set out tangent $(0,-tangent.y)$

Implementations MAY use elliptical arcs to render an ellipse.

Rectangle

A simple rectangle shape

Example

Definitions:

If $r=0$, then the rectangle is rendered from the top-right going clockwise:

1. Add vertex $(right,top)$
2. Add vertex $(right,bottom)$
3. Add vertex $(left,bottom)$
4. Add vertex $(left,top)$

If $r>0$, the rounded corners must be taken into account.

1. Add vertex $(right,top+rounded)$
2. Set in tangent $(0,-tangent)$
3. Add vertex $(right,bottom-rounded)$
4. Set out tangent $(0,tangent)$
5. Add vertex $(right-rounded,bottom)$
6. Set in tangent $(tangent,0)$
7. Add vertex $(left+rounded,bottom)$
8. Set out tangent $(-tangent,0)$
9. Add vertex $(left,bottom-rounded)$
10. Set in tangent $(0,tangent)$
11. Add vertex $(left,top+rounded)$
12. Set out tangent $(0,-tangent)$
13. Add vertex $(left+rounded,top)$
14. Set in tangent $(-tangent,0)$
15. Add vertex $(right-rounded,top)$
16. Set out tangent $(tangent,0)$

Path

Custom Bezier shape

Example

PolyStar

Star or regular polygon

Example

Definitions:

1. For $i$ in $[0,points)$
   1. Let $\beta =-\frac{\pi }{2}+\alpha +i·2\dot{\theta }$
   2. Let $V_{out}=(or·\cos (\beta ),or·\sin (\beta ))$
   3. Add vertex $p+V_{out}$
   4. If $or\ne 0$, we need to add bezier tangent
      1. Let $T_{out}=(V_{out}·\frac{ta{n}_{out}}{or})$
      2. Set in tangent $V_{out}$
      3. Set out tangent $-V_{out}$
   5. If $sy=1$, we need to add a vertex towards the inner radius to make a star
      1. Let $V_{in}=(ir·\cos (\beta +\theta ),or·\sin (\beta +\theta ))$
      2. Add vertex $p+V_{in}$
      3. If $ir\ne 0$, we need to add bezier tangent
         1. Let $T_{in}=(V_{in}·\frac{ta{n}_{in}}{or})$
         2. Set in tangent $V_{in}$
         3. Set out tangent $-V_{in}$

Grouping

Group

Shape Element that can contain other shapes

A group defines a render stack, elements within a group MUST be rendered in reverse order (the first object in the list will appear on top of elements further down).

1. Apply the transform
2. Render Styles and child groups in the transformed coordinate system.

Transform

Group transform

Transform shapes MUST always be present in the group and they MUST be the last item in the it array.

They modify the group's coordinate system the same way as Layer Transform.

Style

Describes the visual appearance (like fill and stroke) of neighbouring shapes

Shapes styles MUST apply their style to the collected shapes that come before them in stacking order.

Fill

Solid fill color

Example

Stroke

Solid stroke

Example

Stroke Dashes

An item used to described the dash pattern in a stroked path

Example

Gradient Fill

Gradient fill color

Example

Gradient Stroke

Gradient stroke

Example

Modifiers

Modifiers change the bezier curves of neighbouring shapes

Modifiers replace shapes in the render stack by applying operating on the bezier path of to the collected shapes that come before it in stacking order.

Trim Path

Trims shapes into a segment

When rendering trim path, the order of bezier points MUST be the same as rendering instructions given for each shape in this section.

Rendering trim path can be rather complex.

Given

If $s$ and $e$ are equal, implementations MUST NOT render any shapes.

If $s=0$ and $e=1$, the input shape MUST be rendered as-is.

To render trim path, implementations MUST consider the actual length of each shape (they MAY use approximations). Once the shapes are collected, the segment to render is given by the percentages $start$ and $end$.

When trim path is applied to multiple shapes, the m property MUST be considered when applying the modifier:

• When m has a value of 1 (Parallel), each shape MUST considered separately, $start$ and $end$ being applied to each shape.

• When m has a value of 2 (Sequential), all the shapes MUST be considered as following each other in render order. $start$ and $end$ refer to the whole length created by concatenating each shape.

Assets

Asset

Precomposition

Asset containing a composition that can be referenced by layers.

Image

Asset containing an image that can be referenced by layers.

Image formats supported vary depending on the player. Some commonly supported formats are JPEG, GIF, PNG and SVG.

If the dimensions of the image asset does not match the size given by w and h, renderers MUST ensure image layers referencing that asset do not have any visuals exceeding the w-h size. It's RECOMMENDED they scale the image maintaining its aspect ratio and they center it within the $(0,0)$, $(w,h)$ box.

Even if an image asset does not have any intrinsic size, its contents MUST still stay within the w-h bounds when rendered.

Authoring tools SHOULD export files where w and h match the physical size of the assets.

Enumerations

Fill Rule

Rule used to handle multiple shapes rendered with the same fill object

Example

Trim Multiple Shapes

How to handle multiple shapes in trim path

Shape Direction

Drawing direction of the shape curve, useful for trim path

Star Type

Whether a PolyStar is a star or a polygon

Example

Line Cap

Style at the end of a stoked line

Example

Line Join

Style at a sharp corner of a stoked line

Example

Mask Mode

Describes how a mask interacts (blends) with the preceding masks in the stack.

Example

Stroke Dash Type

Type of a dash item in a stroked line

Matte Mode

How a layer should mask another layer

The value for Luma is calculated according to Rec.709 standard:

Example

Gradient Type

Whether a Gradient is a linear or radial.

Example

Helpers

Transform

Layer transform