--- metadata: - name: generator content: Diplodoc Platform v5.70.0 alternate: - https://divkit.tech/docs/en/concepts/extensions/lottie.md - https://divkit.tech/docs/ru/concepts/extensions/lottie.md - href: https://divkit.tech/docs/en/concepts/extensions/lottie.md type: text/markdown title: Markdown version - href: https://divkit.tech/docs/en/llms.txt?revision=r22102947 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/en/llms.txt?revision=r22102947 # Lottie animations The `lottie` extension shows a [Lottie](https://lottiefiles.com/) animation in the [gif-image](https://divkit.tech/docs/en/concepts/divs/2/div-gif-image.md) element instead of the GIF image. To connect the animation to a [gif image](https://divkit.tech/docs/en/concepts/divs/2/div-gif-image.md), fill in the `extensions` array: ```json translate=no { "extensions": [ { "id": "lottie", "params": { "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json", "repeat_count": 3, "repeat_mode": "restart" } } ] } ``` {% note info %} **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 {% endnote %} ## Parameters {#params} #| || **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](#repeats). || || `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 {#repeats} 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: {% cut "Example" %} ```json translate=no { "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. {% endcut %} #| || **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 {#scale} The animation is scaled according to the `scale` property of the [gif-image](https://divkit.tech/docs/en/concepts/divs/2/div-gif-image.md) element, the same way as a GIF image. ## Controlling Lottie with actions {#lottie-action} Use [extension_action](https://divkit.tech/docs/en/concepts/divs/2/div-action-extension-action.md) 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: ```json translate=no { "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 {#connect} For an example of connecting the extension handler on Android and Web, see [Connection](https://divkit.tech/docs/en/concepts/extensions.md#connect). 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: ```swift translate=no 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](https://github.com/airbnb/lottie-ios) library, see the [DivKit Playground app](https://github.com/divkit/divkit/blob/main/client/ios/DivKitPlayground/DivKit/LottieAnimationFactory.swift). - `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 {#troubleshooting} You can discuss topics of interest in the DivKit user community in Telegram: [https://t.me/divkit_community_en](https://t.me/divkit_community_en). [DivKit Repository](https://github.com/divkit/divkit)