dotLottie Flutter

June 18, 2026 · View on GitHub

A Flutter plugin for rendering Lottie and dotLottie animations with full playback control, state machine support, and cross-platform compatibility.

Platforms supported: iOS, Android, macOS, Web, Windows, and Linux

Built on top of native implementations:

iOS/macOS
Android
Web
Windows & Linux: dotlottie-rs via FFI

Features

✨ Play Lottie and dotLottie animations
🎮 Full playback control (play, pause, stop, seek)
🔄 State machine support with interactive inputs
🎨 Theme support
📱 Cross-platform: iOS, Android, macOS, Web, Windows, and Linux

Installation
Quick Start
Properties
Methods
Events
State Machines
Platform Notes
Developer Setup

Installation

With Flutter:

flutter pub add dotlottie-flutter

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get)

Import it in your Dart code:

import 'package:dotlottie_flutter/dotlottie_flutter.dart';

Android

To allow dotlottie-android to download, ensure you have jitpack inside your build.gradle.kts file:

maven { url = uri("https://jitpack.io") }

The Windows renderer uses the pre-built dotlottie_player.dll bundled with the plugin (x86_64 and ARM64 are both included). No additional setup is required — Flutter's cmake build copies the DLL into your app bundle automatically.

Linux

The Linux renderer uses the pre-built libdotlottie_rs.so bundled with the plugin (x86_64 and ARM64 are both included). No additional setup is required — Flutter's cmake build copies the shared library into your app bundle automatically.

Ubuntu 24.04 note: If you are using clang 18 from the LLVM apt repository and encounter a type_traits build error, install libc++-dev:
sudo apt-get install libc++-dev libc++abi-dev

Quick Start

import 'package:flutter/material.dart';
import 'package:dotlottie_flutter/dotlottie_flutter.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  DotLottieViewController? _controller;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('dotLottie Example')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              // DotLottie animation view
              SizedBox(
                width: 300,
                height: 300,
                child: DotLottieView(
                  sourceType: 'url',
                  source: 'https://lottie.host/your-animation.lottie',
                  autoplay: true,
                  loop: true,
                  onViewCreated: (controller) {
                    _controller = controller;
                  },
                  onLoad: () {
                     // Do something
                  }
                ),
              ),
              
              const SizedBox(height: 20),
              
              // Basic playback controls
              Row(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  ElevatedButton(
                    onPressed: () => _controller?.play(),
                    child: const Text('Play'),
                  ),
                  const SizedBox(width: 10),
                  ElevatedButton(
                    onPressed: () => _controller?.pause(),
                    child: const Text('Pause'),
                  ),
                  const SizedBox(width: 10),
                  ElevatedButton(
                    onPressed: () => _controller?.stop(),
                    child: const Text('Stop'),
                  ),
                ],
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Properties

Required Properties

Property	Type	Description
`source`	`String`	The source of the animation (URL, asset path, or JSON string)
`sourceType`	`String`	Type of source: `'url'`, `'asset'`, or `'json'`

Playback Properties

Property	Type	Default	Description
`autoplay`	`bool`	`false`	Whether the animation should start playing automatically
`loop`	`bool`	`false`	Whether the animation should loop
`loopCount`	`int?`	`null`	Number of times to loop (overrides `loop` if set)
`speed`	`double`	`1.0`	Playback speed multiplier (e.g., `2.0` for double speed)
`mode`	`String?`	`null`	Playback mode: `'forward'`, `'reverse'`, `'bounce'`, or `'reverse-bounce'`
`useFrameInterpolation`	`bool`	`false`	Enable frame interpolation for smoother playback

Animation Control

Property	Type	Description
`segment`	`List<double>?`	Play a specific segment `[startFrame, endFrame]`
`marker`	`String?`	Play from a named marker defined in the animation
`animationId`	`String?`	ID of a specific animation to play (for multi-animation files)

Visual Properties

Property	Type	Description
`backgroundColor`	`String?`	Background color in hex format (e.g., `'#FF0000'`)
`width`	`double?`	Canvas width for rendering
`height`	`double?`	Canvas height for rendering

Advanced Properties

Property	Type	Description
`themeId`	`String?`	ID of a theme to apply to the animation
`stateMachineId`	`String?`	ID of a state machine to load and start automatically

Example Usage

DotLottieView(
  source: 'https://lottie.host/your-animation.lottie',
  sourceType: 'url',
  autoplay: true,
  loop: true,
  speed: 1.5,
  mode: 'bounce',
  backgroundColor: '#FFFFFF',
  useFrameInterpolation: true,
  onViewCreated: (controller) {
    // Access controller for programmatic control
  },
)

State Machine Example

DotLottieView(
  source: 'https://lottie.host/your-animation.lottie',
  sourceType: 'url',
  stateMachineId: 'myStateMachine',
  onViewCreated: (controller) {
    _controller = controller;
  },
  stateMachineOnStateEntered: (state) {
    print('Entered state: $state');
  },
)

// Interact with the state machine
ElevatedButton(
  onPressed: () {
    _controller?.stateMachineSetBooleanInput('isActive', true);
    _controller?.stateMachineFire('myEvent');
  },
  child: Text('Trigger Event'),
)

Methods

Access these methods via the controller:

DotLottieViewController? _controller;
await _controller?.play();

Playback Control

Method	Returns	Description
`play()`	`Future<bool?>`	Starts playing the animation.
`pause()`	`Future<bool?>`	Pauses the animation.
`stop()`	`Future<bool?>`	Stops the animation and resets to the beginning.

Animation State Getters

Method	Returns	Description
`isPlaying()`	`Future<bool?>`	Returns whether the animation is currently playing.
`isPaused()`	`Future<bool?>`	Returns whether the animation is paused.
`isStopped()`	`Future<bool?>`	Returns whether the animation is stopped.
`isLoaded()`	`Future<bool?>`	Returns whether the animation has loaded.
`currentFrame()`	`Future<double?>`	Gets the current frame number.
`totalFrames()`	`Future<double?>`	Gets the total number of frames.
`currentProgress()`	`Future<double?>`	Gets the current progress (0.0 to 1.0).
`duration()`	`Future<double?>`	Gets the animation duration in milliseconds.
`loopCount()`	`Future<int?>`	Gets the current loop count.
`speed()`	`Future<double?>`	Gets the current playback speed.
`loop()`	`Future<bool?>`	Gets the loop setting.
`autoplay()`	`Future<bool?>`	Gets the autoplay setting.
`useFrameInterpolation()`	`Future<bool?>`	Gets the frame interpolation setting.
`segments()`	`Future<List<double>?>`	Gets the active segment `[start, end]`.
`mode()`	`Future<String?>`	Gets the current playback mode.

Animation Control Setters

Method	Returns	Description
`setSpeed(double speed)`	`Future<void>`	Sets the playback speed.
`setLoop(bool loop)`	`Future<void>`	Sets whether the animation should loop.
`setFrame(double frame)`	`Future<bool?>`	Sets the current frame.
`setProgress(double progress)`	`Future<bool?>`	Sets the progress (0.0 to 1.0).
`setSegments(double start, double end)`	`Future<void>`	Sets a segment of the animation to play.
`setMarker(String marker)`	`Future<void>`	Sets a marker for playback.
`setMode(String mode)`	`Future<void>`	Sets the playback mode.
`setFrameInterpolation(bool useFrameInterpolation)`	`Future<void>`	Enables or disables frame interpolation.

Theme Methods

Method	Returns	Description
`setTheme(String themeId)`	`Future<bool?>`	Applies a theme by ID.
`setThemeData(String themeData)`	`Future<bool?>`	Applies a theme using JSON data.
`resetTheme()`	`Future<bool?>`	Resets to the default theme.
`activeThemeId()`	`Future<String?>`	Gets the currently active theme ID.

Animation Loading

Method	Returns	Description
`loadAnimation(String animationId)`	`Future<void>`	Loads a specific animation by ID.
`activeAnimationId()`	`Future<String?>`	Gets the currently active animation ID.
`markers()`	`Future<List<Map<String, dynamic>>?>`	Gets all available markers.

Advanced Features

Method	Returns	Description
`setSlots(String slots)`	`Future<bool?>`	Sets slot data for dynamic content.
`resize(int width, int height)`	`Future<void>`	Resizes the animation viewport.
`getLayerBounds(String layerName)`	`Future<List<double>?>`	Gets the bounds of a specific layer.
`manifest()`	`Future<Map<String, dynamic>?>`	Gets the animation manifest data.

State Machine Methods

Method	Returns	Description
`stateMachineLoad(String stateMachineId)`	`Future<bool?>`	Loads a state machine by ID.
`stateMachineLoadData(String data)`	`Future<bool?>`	Loads a state machine from JSON data.
`stateMachineStart()`	`Future<bool?>`	Starts the loaded state machine.
`stateMachineStop()`	`Future<bool?>`	Stops the state machine.
`stateMachineFire(String event)`	`Future<void>`	Fires a named event in the state machine.
`stateMachineSetNumericInput(String key, double value)`	`Future<bool?>`	Sets a numeric input value.
`stateMachineSetStringInput(String key, String value)`	`Future<bool?>`	Sets a string input value.
`stateMachineSetBooleanInput(String key, bool value)`	`Future<bool?>`	Sets a boolean input value.
`stateMachineGetNumericInput(String key)`	`Future<double?>`	Gets a numeric input value.
`stateMachineGetStringInput(String key)`	`Future<String?>`	Gets a string input value.
`stateMachineGetBooleanInput(String key)`	`Future<bool?>`	Gets a boolean input value.
`stateMachineGetInputs()`	`Future<Map<String, String>?>`	Gets all input names and their types.
`stateMachineCurrentState()`	`Future<String?>`	Gets the current state name.
`getStateMachine(String id)`	`Future<String?>`	Gets state machine data by ID.

Cleanup

Method	Returns	Description
`dispose()`	`Future<void>`	Disposes of the controller and releases resources.

Events

Add listeners to events on the widget:

DotLottieView(
   onFrame: (frameNo) {
      // Do something
   }
)

Event	Description
`onLoad` → `void Function()?`	Called when the animation is loaded.
`onComplete` → `void Function()?`	Called when the animation completes.
`onLoadError` → `void Function()?`	Called when there's an error loading the animation.
`onPlay` → `void Function()?`	Called when the animation starts playing.
`onPause` → `void Function()?`	Called when the animation is paused.
`onStop` → `void Function()?`	Called when the animation is stopped.
`onLoop` → `void Function(double loopCount)?`	Called when the animation loops, with the current loop count.
`onFrame` → `void Function(double frameNo)?`	Called on each frame update.
`onRender` → `void Function(double frameNo)?`	Called when a frame is rendered.
`onFreeze` → `void Function()?`	Called when the animation is frozen.
`onUnFreeze` → `void Function()?`	Called when the animation is unfrozen.
`onDestroy` → `void Function()?`	Called when the animation is destroyed.

State Machine Events

Event	Description
`stateMachineOnStart` → `void Function()?`	Called when the state machine starts.
`stateMachineOnStop` → `void Function()?`	Called when the state machine stops.
`stateMachineOnStateEntered` → `void Function(String enteringState)?`	Called when entering a new state.
`stateMachineOnStateExit` → `void Function(String leavingState)?`	Called when exiting a state.
`stateMachineOnTransition` → `void Function(String previousState, String newState)?`	Called during a state transition.
`stateMachineOnBooleanInputValueChange` → `void Function(String inputName, bool oldValue, bool newValue)?`	Called when a boolean input changes.
`stateMachineOnNumericInputValueChange` → `void Function(String inputName, double oldValue, double newValue)?`	Called when a numeric input changes.
`stateMachineOnStringInputValueChange` → `void Function(String inputName, String oldValue, String newValue)?`	Called when a string input changes.
`stateMachineOnInputFired` → `void Function(String inputName)?`	Called when an input event is fired.
`stateMachineOnCustomEvent` → `void Function(String message)?`	Called when a custom state machine event occurs.
`stateMachineOnError` → `void Function(String message)?`	Called when a state machine error occurs.

Platform Notes

Windows & Linux

The Windows and Linux implementations use dotlottie-rs via Dart FFI and render directly into a Flutter texture. The following features are supported:

Feature	Supported
Play / Pause / Stop	✅
Seek (setFrame, setProgress)	✅
Loop, Speed, Mode, Frame interpolation	✅
Load from URL, asset, or JSON	✅
onLoad, onPlay, onPause, onStop, onComplete, onLoop, onFrame, onRender	✅
Themes	✅
Markers / Segments	✅
Multi-animation manifest	✅
State machines	✅
State machine pointer interactivity (hover / click / drag)	✅

Pointer events are forwarded to the state machine from Flutter directly (there is no native view managing them on desktop). To avoid unnecessary work, only the pointer listeners a state machine actually declares — via its framework setup — are attached, so move/hover events are not forwarded unless the state machine uses them.

Contributing

See the development guide to learn how to get up and running with this project. Once you're ready, please submit a pull request and we will review it! Thanks!

License

MIT