circular_time_range_picker

A highly customizable circular time range picker for Flutter. Perfect for use cases like sleep tracking, focus sessions, or scheduling, where users select a start and end time on a 24-hour clock face.

Features

• 24h Circular Selection: Intuitive 360-degree time range picking.
• Flexible Interaction:
  • Drag the start handle to adjust the beginning.
  • Drag the end handle to adjust the end.
  • Drag the entire arc to shift the whole time range at once.
• Smart Snapping: Fully configurable minuteInterval (e.g., 5, 10, 15, 30 min) with multiple snapping strategies (round, floor, ceil).
• Highly Customizable UI:
  • Support for Gradients on the range arc.
  • Use Custom Widgets (Icons, Images) as handles.
  • Adjustable stroke width, track colors, and handle sizes.
• Midnight Logic: Automatically calculates durations that cross the midnight threshold (e.g., 23:00 to 07:00).

Getting started

Add the package to your pubspec.yaml:

dependencies:
  circular_time_range_picker: ^0.1.0

Import it in your Dart code:

import 'package:circular_time_range_picker/circular_time_range_picker.dart';

Usage

Simple Example

The most basic implementation requires an initialValue and an onChanged callback.

CircularTimeRangePicker(
  initialValue: const TimeRangeValue(
    start: TimeOfDay(hour: 22, minute: 0),
    end: TimeOfDay(hour: 6, minute: 0),
  ),
  onChanged: (newRange) {
    print("New Duration: ${newRange.duration.inHours} hours");
  },
)

Advanced Styling & Snapping

You can use TimePickerStyle and SnapStrategy to match your app's design and UX requirements.

CircularTimeRangePicker(
  initialValue: _myRange,
  size: const Size(280, 280),
  minuteInterval: 15, 
  snapStrategy: SnapStrategy.round,
  style: TimePickerStyle(
    trackColor: Colors.white10,
    rangeGradient: [Colors.indigoAccent, Colors.deepOrangeAccent],
    strokeWidth: 40,
    handlerRadius: 22,
    startHandlerWidget: const Icon(Icons.bed, color: Colors.indigo, size: 24),
    endHandlerWidget: const Icon(Icons.sunny, color: Colors.orange, size: 24),
  ),
  onChanged: (range) => setState(() => _myRange = range),
)

API Reference

CircularTimeRangePicker

CircularTimeRangePicker({
  Key? key,
  Size size = const Size(250, 250),
  required TimeRangeValue initialValue,
  TimePickerStyle style = const TimePickerStyle(),
  required void Function(TimeRangeValue) onChanged,
  int minuteInterval = 10,
  SnapStrategy snapStrategy = SnapStrategy.round,
})

• initialValue: initial start/end TimeOfDay.
• onChanged: called whenever the user drags a handle or arc.
• minuteInterval:
  • “snap step” in minutes (e.g. 1, 5, 10, 15, 30, 60).
  • Any int >= 1 is allowed, but divisors of 60 (1, 5, 10, 12, 15, 20, 30, 60) are recommended.
• snapStrategy (SnapStrategy):
  • SnapStrategy.round – snap to the nearest interval (default)
  • SnapStrategy.floor – always snap down
  • SnapStrategy.ceil – always snap up
  • SnapStrategy.none – no snapping (in this case minuteInterval is ignored)

Internally, both:

• the displayed times and
• the handle positions (angles)

are snapped according to these settings, so the UI and values stay perfectly in sync.

TimeRangeValue

class TimeRangeValue {
  final TimeOfDay start;
  final TimeOfDay end;

  const TimeRangeValue({required this.start, required this.end});

  Duration get duration;
}

• start / end: 24‑hour times.
• duration:
  • Computed as the forward difference from start to end.
  • Handles ranges that cross midnight (e.g. 23:00 → 07:00 = 8 hours).

TimePickerStyle

class TimePickerStyle {
  final Color trackColor;
  final List<Color> rangeGradient;
  final double strokeWidth;
  final double handlerRadius;
  final Color handlerColor;
  final Widget? startHandlerWidget;
  final Widget? endHandlerWidget;

  const TimePickerStyle({
    this.trackColor = Colors.white10,
    this.rangeGradient = const [Colors.indigoAccent, Colors.deepOrangeAccent],
    this.strokeWidth = 30.0,
    this.handlerRadius = 18.0,
    this.handlerColor = Colors.white,
    this.startHandlerWidget,
    this.endHandlerWidget,
  });
}

• trackColor: background ring color.
• rangeGradient: gradient along the active arc (start → end).
• strokeWidth: thickness of the ring.
• handlerRadius / handlerColor:
• base circular handlers drawn by the painter.
• startHandlerWidget / endHandlerWidget:
• Optional custom widgets rendered on top of the handles, positioned so that their centers sit exactly on the ring.

Example:

style: TimePickerStyle(
  trackColor: const Color(0xFFEEEEEE),
  rangeGradient: const [Colors.blue, Colors.lightBlueAccent],
  strokeWidth: 40,
  handlerRadius: 20,
  handlerColor: Colors.white,
  startHandlerWidget: const Icon(Icons.bed, color: Colors.white),
  endHandlerWidget: const Icon(Icons.sunny, color: Colors.white),
),

FAQ

Q: How do I display the total duration in the center?

A: Wrap the CircularTimeRangePicker in a Stack and place a Text widget in the center. Since the picker's center is transparent, the text will be visible.

Q: Does it support 12-hour or 24-hour formats?

A: The picker always operates on a 24-hour logic (full circle), but you can format the output TimeOfDay to 12h or 24h format in your UI using timeOfDay.format(context).

License

This package is distributed under the MIT License. See LICENSE for details.