Events

Handle animation lifecycle and state changes with event listeners.

Adding Event Listeners

Add event listeners directly to the DotLottieView widget:

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  onLoad: () {
    print('Animation loaded!');
  },
  onPlay: () {
    print('Animation started playing');
  },
  onComplete: () {
    print('Animation completed');
  },
)

Animation Lifecycle Events

Events that track the animation’s lifecycle.

Event	Signature	Description
`onLoad`	`void Function()?`	Called when the animation is loaded
`onLoadError`	`void Function()?`	Called when there’s an error loading the animation
`onDestroy`	`void Function()?`	Called when the animation is destroyed

Example

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  onLoad: () {
    print('✓ Animation loaded successfully');
    // Safe to call controller methods now
  },
  onLoadError: () {
    print('✗ Failed to load animation');
    // Show error message to user
  },
  onDestroy: () {
    print('Animation destroyed');
    // Cleanup any related resources
  },
)

Playback Events

Events that track playback state changes.

Event	Signature	Description
`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
`onComplete`	`void Function()?`	Called when the animation completes
`onLoop`	`void Function(double loopCount)?`	Called when the animation loops, with the current loop count

Example

int _loopCount = 0;

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  loop: true,
  onPlay: () {
    setState(() {
      _isPlaying = true;
    });
  },
  onPause: () {
    setState(() {
      _isPlaying = false;
    });
  },
  onComplete: () {
    print('Animation completed');
    // Show completion message or trigger next action
  },
  onLoop: (loopCount) {
    setState(() {
      _loopCount = loopCount.toInt();
    });
    print('Loop #$loopCount');
  },
)

Frame Events

Events that fire during animation playback.

Event	Signature	Description
`onFrame`	`void Function(double frameNo)?`	Called on each frame update
`onRender`	`void Function(double frameNo)?`	Called when a frame is rendered

Example

double _currentFrame = 0;

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  autoplay: true,
  onFrame: (frameNo) {
    setState(() {
      _currentFrame = frameNo;
    });
  },
  onRender: (frameNo) {
    // Use sparingly - fires frequently
    // Good for debugging or precise frame tracking
  },
)

// Display current frame
Text('Frame: ${_currentFrame.toInt()}')

State Machine Events

Events for state machine interactions. See the State Machines Guide for detailed examples.

Event	Signature	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

Example

String _currentState = 'idle';

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  stateMachineId: 'myStateMachine',
  stateMachineOnStart: () {
    print('State machine started');
  },
  stateMachineOnStateEntered: (state) {
    setState(() {
      _currentState = state;
    });
    print('Entered state: $state');
  },
  stateMachineOnTransition: (previousState, newState) {
    print('Transition: $previousState → $newState');
  },
)

// Display current state
Text('State: $_currentState')

State Machine Input Events

Events that fire when state machine inputs change.

Event	Signature	Description
`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

Example

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  stateMachineId: 'myStateMachine',
  stateMachineOnBooleanInputValueChange: (name, oldValue, newValue) {
    print('$name changed: $oldValue → $newValue');
  },
  stateMachineOnNumericInputValueChange: (name, oldValue, newValue) {
    print('$name changed: $oldValue → $newValue');
  },
  stateMachineOnInputFired: (name) {
    print('Input fired: $name');
  },
)

State Machine Error and Custom Events

Handle state machine errors and custom events.

Event	Signature	Description
`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

Example

DotLottieView(
  source: 'assets/animation.lottie',
  sourceType: 'asset',
  stateMachineId: 'myStateMachine',
  stateMachineOnCustomEvent: (message) {
    print('Custom event: $message');
    // Handle custom logic based on message
  },
  stateMachineOnError: (message) {
    print('State machine error: $message');
    // Show error to user or fallback behavior
  },
)

Complete Example

class AnimationScreen extends StatefulWidget {
  @override
  State<AnimationScreen> createState() => _AnimationScreenState();
}

class _AnimationScreenState extends State<AnimationScreen> {
  bool _isLoaded = false;
  bool _isPlaying = false;
  double _currentFrame = 0;
  int _loopCount = 0;
  String _currentState = 'idle';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Event Handling')),
      body: Column(
        children: [
          // Animation
          Expanded(
            child: DotLottieView(
              source: 'assets/animation.lottie',
              sourceType: 'asset',
              autoplay: true,
              loop: true,
              stateMachineId: 'interactive',

              // Lifecycle
              onLoad: () {
                setState(() => _isLoaded = true);
              },
              onLoadError: () {
                ScaffoldMessenger.of(context).showSnackBar(
                  const SnackBar(content: Text('Failed to load animation')),
                );
              },

              // Playback
              onPlay: () {
                setState(() => _isPlaying = true);
              },
              onPause: () {
                setState(() => _isPlaying = false);
              },
              onLoop: (count) {
                setState(() => _loopCount = count.toInt());
              },

              // Frames
              onFrame: (frame) {
                setState(() => _currentFrame = frame);
              },

              // State machine
              stateMachineOnStateEntered: (state) {
                setState(() => _currentState = state);
              },
            ),
          ),

          // Status display
          Padding(
            padding: const EdgeInsets.all(16.0),
            child: Column(
              children: [
                Text('Loaded: $_isLoaded'),
                Text('Playing: $_isPlaying'),
                Text('Frame: ${_currentFrame.toInt()}'),
                Text('Loops: $_loopCount'),
                Text('State: $_currentState'),
              ],
            ),
          ),
        ],
      ),
    );
  }
}