Lottie animations

The lottie extension shows a Lottie animation in the gif-image element instead of the GIF image.

To connect the animation to a gif image, fill in the extensions array:

{
  "extensions": [
    {
      "id": "lottie",
      "params": {
        "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json",
        "repeat_count": 3,
        "repeat_mode": "restart"
      }
    }
  ]
}

Note

repeat_count parameter behavior

repeat_count: 0 — animation plays once
repeat_count: 1 — animation plays twice
repeat_count: N — animation plays N+1 times
repeat_count: -1 — infinite looping

Parameters

Parameters	Description
`id`	Extension ID.
`lottie_url`	Required URL to Lottie JSON if the `lottie_json` parameter isn't specified. On Android, it can work according to the `asset:{address}` or `res:{address}` schemes for embedded resources. Resource binding in these schemes occurs via the `DivLottieRawResProvider` dependency that is passed to `DivLottieExtensionHandler`. On Android, the animation is preloaded for URLs with the `http` and `https` schemes.
`lottie_json`	Required parameter if `lottie_url` isn't specified. Contains Lottie JSON as an object. Specify only one of the `lottie_url` and `lottie_json` parameters: if both are specified, the source that is used depends on the platform.
`repeat_count`	The number of animation repetitions. Use the `-1` value for an infinite number of repetitions. The default value depends on the platform, so specify the parameter explicitly.
`repeat_mode`	The action after the animation ends. It can have the values: `restart`: Animation restarts. `reverse`: Animation is displayed frame-by-frame in reverse order. Default: `restart`.
`repeats`	Playback stages with separate frame ranges (Android only). See Playback stages.
`is_playing`	Controls automatic animation playback during initialization. If set to `false`, the animation won't start automatically. If the value is an expression, changing it pauses or resumes playback. Default: `true`.
`safe_mode`	If set to `true`, an error while drawing an animation frame doesn't crash the application: the frame isn't displayed (Android only). Default: `false`.

The lottie_url, repeat_count, repeat_mode, and is_playing parameters support expressions.

Playback stages

On Android, you can split the animation into stages. Each stage plays its own frame range the specified number of times, and then the next stage starts. List the stages in the repeats array:

Example

{
  "extensions": [
    {
      "id": "lottie",
      "params": {
        "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json",
        "repeat_count": -1,
        "repeats": [
          {
            "repeat_count": 0,
            "min_frame": 0,
            "max_frame": 30
          },
          {
            "repeat_count": -1,
            "repeat_mode": "restart",
            "min_frame": 30,
            "max_frame": 90
          }
        ]
      }
    }
  ]
}

In this example, frames 0 to 30 are played once, and then frames 30 to 90 are repeated infinitely.

Stage parameters	Description
`repeat_count`	The number of repetitions of the stage. The values are the same as for the `repeat_count` parameter of the extension. Default: `1`.
`repeat_mode`	The action after a pass ends: `restart` or `reverse`. Default: `restart`.
`min_frame`	The frame the stage starts from. Default: the first frame of the animation.
`max_frame`	The frame the stage ends at. Default: the last frame of the animation.

If the repeats array contains at least one stage, the repeat_count and repeat_mode parameters of the extension aren't used on Android. Other platforms ignore the repeats array: the whole animation is played according to the repeat_count and repeat_mode parameters.

Scaling

The animation is scaled according to the scale property of the gif-image element, the same way as a GIF image.

Controlling Lottie with actions

Use extension_action to send a command to the lottie extension attached to the element identified by div_id. Put the command in the outer action's payload, alongside typed.

start rewinds the animation and starts playback from the beginning; stop rewinds it and leaves it stopped. For example, to restart the animation:

{
  "log_id": "start_lottie",
  "typed": {
    "type": "extension_action",
    "div_id": "my_div",
    "extension_id": "lottie"
  },
  "payload": {
    "type": "start"
  }
}

To stop it, replace "type": "start" in payload with "type": "stop".

After a start or stop command, playback is controlled by commands: the is_playing value doesn't affect it.

Connection

For an example of connecting the extension handler on Android and Web, see Connection.

On iOS, DivKit doesn't depend on a Lottie playback library. Pass a factory to LottieExtensionHandler: it implements the AsyncSourceAnimatableViewFactory protocol and creates the view that plays the animation:

let lottieExtensionHandler = LottieExtensionHandler(
  factory: LottieAnimationFactory(),
  requester: requester
)

factory: Factory of the animation view. It also defines how many times the animation is played for the specified repeat_count and repeat_mode. For a sample factory for the lottie-ios library, see the DivKit Playground app.
requester: URLResourceRequesting object that loads the animation file from the lottie_url URL.

For the start and stop commands to work on iOS, the animation view must conform to the LottiePlaybackControlling protocol.

Learn more

You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.

DivKit Repository

Was the article helpful?

Extensions

Pinch-to-zoom