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

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.
`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<bool?>`	Starts or resumes playback.
`pause()`	`Future<bool?>`	Pauses playback.
`stop()`	`Future<bool?>`	Stops playback and resets to the first frame.
`setFrame(double frame)`	`Future<bool?>`	Jumps to the specified frame.
`setProgress(double progress)`	`Future<bool?>`	Jumps to the specified progress (0.0–1.0).
`setSpeed(double speed)`	`Future<void>`	Sets the playback speed multiplier.
`setLoop(bool loop)`	`Future<void>`	Enables or disables looping.
`setMode(String mode)`	`Future<void>`	Sets the playback mode.
`setSegments(double start, double end)`	`Future<void>`	Sets the frame range to play.
`setMarker(String marker)`	`Future<void>`	Sets the named marker to play.
`setFrameInterpolation(bool value)`	`Future<void>`	Enables or disables subframe interpolation.
`resize(int width, int height)`	`Future<void>`	Resizes the animation canvas.

State Queries

Method	Return Type	Description
`isPlaying()`	`Future<bool?>`	Returns `true` if the animation is playing.
`isPaused()`	`Future<bool?>`	Returns `true` if paused.
`isStopped()`	`Future<bool?>`	Returns `true` if stopped.
`isLoaded()`	`Future<bool?>`	Returns `true` if the animation is loaded.
`currentFrame()`	`Future<double?>`	Returns the current frame number.
`totalFrames()`	`Future<double?>`	Returns the total number of frames.
`currentProgress()`	`Future<double?>`	Returns the current progress (0.0–1.0).
`duration()`	`Future<double?>`	Returns the animation duration in milliseconds.
`speed()`	`Future<double?>`	Returns the current playback speed.
`loop()`	`Future<bool?>`	Returns the current loop setting.
`autoplay()`	`Future<bool?>`	Returns the current autoplay setting.
`loopCount()`	`Future<int?>`	Returns the current loop count.
`segments()`	`Future<List<double>?>`	Returns the current frame segment.
`mode()`	`Future<String?>`	Returns the current playback mode.
`useFrameInterpolation()`	`Future<bool?>`	Returns whether subframe interpolation is on.

Animation & Theme

Method	Return Type	Description
`loadAnimation(String animationId)`	`Future<void>`	Loads a specific animation by ID.
`activeAnimationId()`	`Future<String?>`	Returns the ID of the currently active animation.
`activeThemeId()`	`Future<String?>`	Returns the ID of the currently active theme.
`setTheme(String themeId)`	`Future<bool?>`	Applies a theme by ID.
`setThemeData(String themeData)`	`Future<bool?>`	Applies a theme from a raw JSON string.
`resetTheme()`	`Future<bool?>`	Resets to the default theme.
`markers()`	`Future<List<Map<String, dynamic>>?>`	Returns the list of available markers.
`manifest()`	`Future<Map<String, dynamic>?>`	Returns the dotLottie manifest.

Slots

Method	Return Type	Description
`setSlots(String slots)`	`Future<bool?>`	Sets multiple slot values from a JSON string.

Layer Utilities

Method	Return Type	Description
`getLayerBounds(String layerName)`	`Future<List<double>?>`	Returns the bounding box of the named layer.

State Machine

Method	Return Type	Description
`stateMachineLoad(String id)`	`Future<void>`	Loads a state machine by ID.
`stateMachineLoadData(String data)`	`Future<void>`	Loads a state machine from a raw JSON string.
`stateMachineStart()`	`Future<void>`	Starts the loaded state machine.
`stateMachineStop()`	`Future<void>`	Stops the state machine.
`stateMachineFire(String event)`	`Future<void>`	Fires a named event to the state machine.
`stateMachineSetBooleanInput(String key, bool value)`	`Future<void>`	Sets a boolean input.
`stateMachineSetNumericInput(String key, double value)`	`Future<void>`	Sets a numeric input.
`stateMachineSetStringInput(String key, String value)`	`Future<void>`	Sets a string input.
`stateMachineGetBooleanInput(String key)`	`Future<bool?>`	Gets a boolean input value.
`stateMachineGetNumericInput(String key)`	`Future<double?>`	Gets a numeric input value.
`stateMachineGetStringInput(String key)`	`Future<String?>`	Gets a string input value.
`stateMachineGetInputs()`	`Future<Map>`	Returns all defined inputs and their values.
`stateMachineCurrentState()`	`Future<String>`	Returns the name of the currently active state.
`getStateMachine(String id)`	`Future<String>`	Returns the state machine definition JSON.
`dispose()`	`Future<void>`	Disposes the controller and releases resources.

Last updated: April 10, 2026 at 9:12 AMEdit this page

Understanding State Machines

Version