# dotLottie Flutter Player API Reference API reference for the dotLottie Flutter player. Details for the DotLottieView widget, DotLottieViewController, and all supported events. # dotLottie Flutter Player API Reference ## DotLottieView Widget The `DotLottieView` widget renders a dotLottie or Lottie animation. ### Configuration Properties | Property | Type | Default | Description | | ----------------------- | ------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | `String` | required | The animation source — a URL, asset path, or JSON string. | | `sourceType` | `String` | required | Source type: `'url'`, `'asset'`, or `'json'`. | | `autoplay` | `bool` | `false` | Auto-starts the animation on load. | | `loop` | `bool` | `false` | Whether the animation loops. | | `loopCount` | `int` | `0` | Number of additional loop repetitions (0 = infinite when `loop` is true). | | `speed` | `double` | `1.0` | Playback speed multiplier. | | `mode` | `String` | `'forward'` | Playback mode: `'forward'`, `'reverse'`, `'bounce'`, `'reverseBounce'`. | | `segment` | `[double, double]?` | `null` | Frame range to play as `[startFrame, endFrame]`. | | `marker` | `String?` | `null` | Named marker to play. | | `fit` | `BoxFit?` | `null` | How the animation is inscribed into its bounds. Accepts any `BoxFit` value. Changing this prop at runtime pushes the new layout to the native player without recreating the view. `BoxFit.scaleDown` is approximated as `BoxFit.contain`. | | `useFrameInterpolation` | `bool` | `false` | Enable subframe interpolation. | | `backgroundColor` | `String?` | `null` | Background color as an 8-digit hex string (e.g., `'#ff0000ff'`). | | `animationId` | `String?` | `null` | ID of the animation to load from a multi-animation `.lottie` file. | | `themeId` | `String?` | `null` | ID of the theme to apply from the `.lottie` file. | | `stateMachineId` | `String?` | `null` | ID of the state machine to load on animation load. | | `width` | `int?` | `null` | Width of the animation canvas. | | `height` | `int?` | `null` | Height of the animation canvas. | | `onViewCreated` | `Function(DotLottieViewController)?` | `null` | Callback invoked with the controller after the player is initialized. | ### Event Callbacks #### Animation Events | Callback | Signature | Description | | ------------- | ------------------- | ----------------------------------- | | `onLoad` | `VoidCallback?` | Fired when the animation is loaded. | | `onComplete` | `VoidCallback?` | Fired when playback completes. | | `onLoadError` | `VoidCallback?` | Fired when loading fails. | | `onPlay` | `VoidCallback?` | Fired when playback starts. | | `onPause` | `VoidCallback?` | Fired when playback pauses. | | `onStop` | `VoidCallback?` | Fired when playback stops. | | `onFrame` | `Function(double)?` | Fired on each frame update. | | `onRender` | `Function(double)?` | Fired when a new frame is rendered. | | `onLoop` | `Function(int)?` | Fired when a loop completes. | #### State Machine Events | Callback | Signature | Description | | --------------------------------------- | ------------------------------------------------ | --------------------------------------------------- | | `stateMachineOnStart` | `VoidCallback?` | Fired when the state machine starts. | | `stateMachineOnStop` | `VoidCallback?` | Fired when the state machine stops. | | `stateMachineOnTransition` | `Function(String from, String to)?` | Fired on a state transition. | | `stateMachineOnStateEntered` | `Function(String state)?` | Fired when entering a state. | | `stateMachineOnStateExit` | `Function(String state)?` | Fired when exiting a state. | | `stateMachineOnCustomEvent` | `Function(String event)?` | Fired when a custom state machine event is emitted. | | `stateMachineOnError` | `Function(String error)?` | Fired when the state machine encounters an error. | | `stateMachineOnInputFired` | `Function(String inputName)?` | Fired when an input fires. | | `stateMachineOnBooleanInputValueChange` | `Function(String name, bool old, bool new)?` | Fired when a boolean input changes. | | `stateMachineOnNumericInputValueChange` | `Function(String name, double old, double new)?` | Fired when a numeric input changes. | | `stateMachineOnStringInputValueChange` | `Function(String name, String old, String new)?` | Fired when a string input changes. | --- ## DotLottieViewController Obtained via `DotLottieView.onViewCreated`. Provides programmatic control over the animation. ### Playback Methods | Method | Return Type | Description | | ---------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `play()` | `Future` | Starts or resumes playback. | | `pause()` | `Future` | Pauses playback. | | `stop()` | `Future` | Stops playback and resets to the first frame. | | `setFrame(double frame)` | `Future` | Jumps to the specified frame. | | `setProgress(double progress)` | `Future` | Jumps to the specified progress (0.0–1.0). | | `setSpeed(double speed)` | `Future` | Sets the playback speed multiplier. | | `setLoop(bool loop)` | `Future` | Enables or disables looping. | | `setMode(String mode)` | `Future` | Sets the playback mode. | | `setSegments(double start, double end)` | `Future` | Sets the frame range to play. | | `setMarker(String marker)` | `Future` | Sets the named marker to play. | | `setFrameInterpolation(bool value)` | `Future` | Enables or disables subframe interpolation. | | `resize(int width, int height)` | `Future` | Resizes the animation canvas. | | `setLayout(BoxFit fit, {Alignment alignment})` | `Future` | Updates how the animation is fitted and aligned within the view at runtime. `alignment` defaults to `Alignment.center`. Takes effect on the next rendered frame without recreating the native view. This is called automatically when the `DotLottieView.fit` prop changes. | ### State Queries | Method | Return Type | Description | | ------------------------- | ----------------------- | ----------------------------------------------- | | `isPlaying()` | `Future` | Returns `true` if the animation is playing. | | `isPaused()` | `Future` | Returns `true` if paused. | | `isStopped()` | `Future` | Returns `true` if stopped. | | `isLoaded()` | `Future` | Returns `true` if the animation is loaded. | | `currentFrame()` | `Future` | Returns the current frame number. | | `totalFrames()` | `Future` | Returns the total number of frames. | | `currentProgress()` | `Future` | Returns the current progress (0.0–1.0). | | `duration()` | `Future` | Returns the animation duration in milliseconds. | | `speed()` | `Future` | Returns the current playback speed. | | `loop()` | `Future` | Returns the current loop setting. | | `autoplay()` | `Future` | Returns the current autoplay setting. | | `loopCount()` | `Future` | Returns the current loop count. | | `segments()` | `Future?>` | Returns the current frame segment. | | `mode()` | `Future` | Returns the current playback mode. | | `useFrameInterpolation()` | `Future` | Returns whether subframe interpolation is on. | ### Animation & Theme | Method | Return Type | Description | | ----------------------------------- | ------------------------------------- | ------------------------------------------------- | | `loadAnimation(String animationId)` | `Future` | Loads a specific animation by ID. | | `activeAnimationId()` | `Future` | Returns the ID of the currently active animation. | | `activeThemeId()` | `Future` | Returns the ID of the currently active theme. | | `setTheme(String themeId)` | `Future` | Applies a theme by ID. | | `setThemeData(String themeData)` | `Future` | Applies a theme from a raw JSON string. | | `resetTheme()` | `Future` | Resets to the default theme. | | `markers()` | `Future>?>` | Returns the list of available markers. | | `manifest()` | `Future?>` | Returns the dotLottie manifest. | ### Slots | Method | Return Type | Description | | ------------------------ | --------------- | --------------------------------------------- | | `setSlots(String slots)` | `Future` | Sets multiple slot values from a JSON string. | ### State Machine | Method | Return Type | Description | | ------------------------------------------------------- | ----------------- | ----------------------------------------------- | | `stateMachineLoad(String id)` | `Future` | Loads a state machine by ID. | | `stateMachineLoadData(String data)` | `Future` | Loads a state machine from a raw JSON string. | | `stateMachineStart()` | `Future` | Starts the loaded state machine. | | `stateMachineStop()` | `Future` | Stops the state machine. | | `stateMachineFire(String event)` | `Future` | Fires a named event to the state machine. | | `stateMachineSetBooleanInput(String key, bool value)` | `Future` | Sets a boolean input. | | `stateMachineSetNumericInput(String key, double value)` | `Future` | Sets a numeric input. | | `stateMachineSetStringInput(String key, String value)` | `Future` | Sets a string input. | | `stateMachineGetBooleanInput(String key)` | `Future` | Gets a boolean input value. | | `stateMachineGetNumericInput(String key)` | `Future` | Gets a numeric input value. | | `stateMachineGetStringInput(String key)` | `Future` | Gets a string input value. | | `stateMachineGetInputs()` | `Future` | Returns all defined inputs and their values. | | `stateMachineCurrentState()` | `Future` | Returns the name of the currently active state. | | `getStateMachine(String id)` | `Future` | Returns the state machine definition JSON. | | `dispose()` | `Future` | Disposes the controller and releases resources. | --- ## Related Topics - [Getting Started](/en/runtimes/distributions/flutter/v0.x/getting-started) - [Examples](/en/runtimes/distributions/flutter/v0.x/examples)