A Flutter package that provides a widget to listen to the system's datetime and trigger a rebuild based on the specified time unit

Support the project by giving the repo a ⭐ and showing some ❤️!

Usage

Import the package in your Dart code:

import 'package:datetime_loop/datetime_loop.dart';

Using DateTimeLoopBuilder

Use the DateTimeLoopBuilder widget to rebuild UI elements based on system time updates. You can provide a timeUnit for simple setups or a custom DateTimeLoopController for advanced control (e.g., pause/resume):

DateTimeLoopBuilder(
  timeUnit: TimeUnit.seconds,
  builder: (context, dateTime, child) {
    return Column(
      children: [
        Container(
          width: 200,
          height: 200,
          color: Color((math.Random().nextDouble() * 0xFFFFFF).toInt()).withOpacity(1.0),
        ),
        Text('$dateTime'),
      ],
    );
  }
)

Using DateTimeLoopController

The DateTimeLoopController provides a stream of datetime updates and supports advanced features like pausing and resuming updates, useful for optimizing resource usage (e.g., when the app is backgrounded):

final controller = DateTimeLoopController(timeUnit: TimeUnit.minutes);
controller.dateTimeStream.listen((dateTime) {
  print('Current time: $dateTime');
});

// Pause updates to save resources
controller.pause();

// Resume updates with an immediate trigger
controller.resume(triggerImmediate: true);

// Use the controller with DateTimeLoopBuilder
DateTimeLoopBuilder(
  controller: controller,
  builder: (context, dateTime, child) {
  return Text('Time: ${dateTime.toString().split('.').first}');
  },
);

// Dispose of the controller when done
controller.dispose();

Testing with getNow

Both DateTimeLoopBuilder and DateTimeLoopController support a getNow parameter that allows you to mock the system time. This is particularly useful for testing and simulating different time scenarios:

// Example: Testing with a mocked time
DateTime customTime = DateTime(2025, 10, 31, 12, 0, 0);

DateTimeLoopBuilder(
  timeUnit: TimeUnit.seconds,
  getNow: () => customTime,
  builder: (context, dateTime, child) {
    return Text('Mocked time: $dateTime');
  },
)

// Example: Using getNow with DateTimeLoopController
final controller = DateTimeLoopController(
  timeUnit: TimeUnit.minutes,
  getNow: () => customTime,
);

This feature enables:

• Unit Testing: Write deterministic tests by controlling the datetime value
• Time Simulation: Simulate different time scenarios without waiting for real time to pass
• Debugging: Test edge cases and time-dependent behavior

You can check more examples of using this widget here

Issues and Feedback

Please file any issues or feedback here.