Round Clock - Time Range Selector

A professional Flutter time range selector widget with a circular clock-based UI. Perfect for selecting sleep/wake times or any 24-hour time range with smooth animations and intuitive drag-based interaction.

Features

✨ Beautiful UI

  • Circular 24-hour clock design
  • Gradient effects on handles and ring
  • Smooth animations and transitions
  • Professional shadows and depth effects

🎨 Theme Support

  • Full Material 3 integration
  • Light and dark mode support
  • Automatic theme adaptation
  • Customizable colors via ColorScheme

🎯 Interactive

  • Drag-based time selection
  • Smart handle detection (40px hit area)
  • Smooth scaling animations
  • Real-time updates

📱 Intelligent

  • Auto-calculated Today/Tomorrow/Tonight labels
  • Based on current system time
  • Proper AM/PM formatting
  • Duration calculation

Installation

Add this to your pubspec.yaml:

dependencies:
  round_clock:
    path: ./round_clock

Then run:

flutter pub get

Usage

Basic Example

import 'package:flutter/material.dart';
import 'package:round_clock/round_clock.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: TimeRangeSelector(
            startHour: 22.0,  // 10:00 PM
            endHour: 7.0,     // 7:00 AM
            onTimeChanged: (start, end) {
              print('Sleep: $start hours, Wake: $end hours');
            },
          ),
        ),
      ),
    );
  }
}

With Custom Theme

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.orange,
      primary: Colors.orange,        // Sleep handle color
      secondary: Colors.amber,       // Wake handle color
    ),
  ),
  home: Scaffold(
    body: TimeRangeSelector(
      startHour: 20.167,
      endHour: 9.867,
      onTimeChanged: (start, end) {
        // Handle time change
      },
    ),
  ),
)

API Reference

TimeRangeSelector

TimeRangeSelector({
  double startHour = 20.167,              // Default: 8:10 PM
  double endHour = 9.867,                 // Default: 9:52 AM
  Function(double, double)? onTimeChanged, // Callback when times change
})

Parameters:

  • startHour (double): Start time in 24-hour format (0-24)

    • 0-11: AM hours
    • 12-23: PM hours
    • Can include decimal for minutes (e.g., 20.5 = 8:30 PM)

  • endHour (double): End time in 24-hour format (0-24)

  • onTimeChanged: Callback function called when either handle is dragged

    • Parameters: (startHour, endHour)

How It Works

Time Format

The widget uses 24-hour decimal format for times:

  • 0.0 = 12:00 AM (midnight)
  • 6.0 = 6:00 AM
  • 12.0 = 12:00 PM (noon)
  • 18.0 = 6:00 PM
  • 20.167 = 8:10 PM (20 + 0.167 * 60 = 20:10)

Smart Labels

Labels automatically adjust based on current time:

  • Today: AM times that haven't passed yet
  • Tonight: PM times that haven't passed yet
  • Tomorrow: Times that have already passed today

Duration Calculation

The widget automatically calculates sleep duration, handling the case where sleep spans midnight:

If end < start: duration = (24 - start) + end
If end >= start: duration = end - start

Customization

Styling via Theme

The widget respects your app's theme:

ThemeData(
  colorScheme: ColorScheme.fromSeed(
    seedColor: Colors.purple,
    primary: Colors.purple,      // Changes handle & arc color
    secondary: Colors.yellow,    // Changes wake handle color
    surface: Colors.white,       // Changes background
  ),
)

Direct Props

TimeRangeSelector(
  startHour: 21.0,    // 9:00 PM
  endHour: 8.0,       // 8:00 AM
  onTimeChanged: (start, end) {
    // Do something with the new times
  },
)

Example App

The package includes a complete example app in lib/main.dart:

flutter run

Widget Size

The widget renders at:

  • Width: 376px
  • Height: 832px

Adjust the parent container size as needed. The widget will scale proportionally.

Platform Support

  • ✅ iOS
  • ✅ Android
  • ✅ macOS
  • ✅ Windows
  • ✅ Linux
  • ✅ Web

License

MIT License - feel free to use in your projects!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ from a Figma design.

Libraries

main
round_clock
A professional Flutter time range selector widget.