How to Build a Multi-Event Countdown Timer in Flutter

Creating a countdown timer that handles multiple simultaneous events is a common requirement for productivity and event-management applications. Whether you are building a pomodoro tracker, a kitchen timer, or an event reminder system, a well-architected Flutter application requires careful state management and background task handling. In this guide, we will explore how to build a multi-event countdown timer featuring custom labels, recurring events, and local notifications.

Understanding the Core Architecture

To manage multiple timers, you need a data model that encapsulates the state of each event. Relying on simple variables is insufficient; instead, use a class to represent your TimerEvent. This allows you to track the duration, the remaining time, the label, and whether the timer should repeat.

The TimerEvent Model

class TimerEvent {
  final String id;
  final String label;
  final Duration duration;
  Duration remaining;
  final bool isRepeating;

  TimerEvent({
    required this.id,
    required this.label,
    required this.duration,
    required this.remaining,
    this.isRepeating = false,
  });
}

Managing Timer State

For managing multiple active timers, ChangeNotifier or Bloc are excellent choices. Using ChangeNotifier provides a straightforward way to update the UI when the remaining duration changes. You will need a Timer.periodic instance to decrement the values of all active timers every second.

Implementing the Timer Controller

class TimerProvider extends ChangeNotifier {
  List<TimerEvent> _events = [];
  List<TimerEvent> get events => _events;

  void startTimer(TimerEvent event) {
    Timer.periodic(Duration(seconds: 1), (timer) {
      if (event.remaining.inSeconds > 0) {
        event.remaining -= Duration(seconds: 1);
        notifyListeners();
      } else {
        timer.cancel();
        _handleTimerCompletion(event);
      }
    });
  }
}

Integrating Local Notifications

To ensure users are alerted even when the app is in the background, the flutter_local_notifications package is essential. You must initialize the plugin and request permissions before scheduling any notifications. For a multi-event system, ensure each notification has a unique ID associated with the TimerEvent.

Scheduling a Notification

Future<void> showNotification(TimerEvent event) async {
  const AndroidNotificationDetails androidDetails = AndroidNotificationDetails(
    'timer_channel', 'Timer Notifications',
    importance: Importance.max, priority: Priority.high,
  );
  await flutterLocalNotificationsPlugin.show(
    event.id.hashCode, 'Timer Finished', 'Your ${event.label} is done!',
    NotificationDetails(android: androidDetails),
  );
}

Building the User Interface

Your UI should be reactive. Use a ListView.builder to display the list of active timers. Wrap each item in a Consumer widget (if using Provider) to ensure that only the specific timer that changed triggers a rebuild. This optimization is crucial for performance when handling many concurrent timers.

Best Practices and Trade-offs

1. Resource Management: Always cancel your Timer objects when the widget is disposed or the timer is deleted to prevent memory leaks.
2. Background Execution: Remember that Timer.periodic stops when the app is suspended. For long-running timers that must persist while the app is closed, consider using native background services or WorkManager.
3. Precision: Timer.periodic is not perfectly precise. For mission-critical timing, compare the current DateTime.now() against the target DateTime rather than simply decrementing a duration variable.

Conclusion

Building a multi-event countdown timer in Flutter involves balancing state management with native notification capabilities. By modeling your events clearly and using efficient rebuild patterns, you can create a responsive and reliable timer application. Always prioritize cleaning up your timer resources and testing notification behavior across different OS versions.

Frequently Asked Questions

Can I use this for long-duration timers?

For timers lasting hours or days, avoid Timer.periodic. Instead, store the target end time and calculate the difference from the current time whenever the UI refreshes.

How do I handle app termination?

Standard Flutter timers stop when the app is terminated. You must use platform-specific background tasks or local notification scheduling to trigger alerts when the app is not running.

Is it possible to have multiple repeat cycles?

Yes, by resetting the remaining duration to the original duration value inside the completion callback of your timer logic.