Advanced Countdown Timer Package #

A professional, feature-rich countdown timer package for Flutter with multiple display styles, advanced animations, comprehensive theming, and full responsive design for all devices (iPhone, iPad, Android, Desktop, Web).

✨ Features #

🎨 Professional Display Styles #

Compact: Icon + time with controls
Detailed: Title + large time display
Circular: Progress ring with time in center
Minimal: Just the time
Bottom Bar: Navigation bar style
Card: Elevated card with rounded corners
Gradient: Background gradient style
Digital: Segmented digital display
Analog: Clock-style display with hands
Progress Bar: Linear progress with time overlay
Floating: Circular floating action button style
Notification: Badge-style notification display
Custom: Complete custom builder support

📱 Full Responsive Design #

Automatic adaptation to iPhone, iPad, Android, and Desktop screen sizes
Smart breakpoints: XS, SM, MD, LG, XL
Device detection: Phone, tablet, desktop identification
Responsive sizing: Fonts, padding, icons, spacing
Custom responsive themes with breakpoint-specific configurations

⚡ Advanced Animation System #

Pulse animation when time is low
Shake animation when timer finishes
Scale animations on state changes
Fade transitions for smooth UX
Custom animation curves and durations
Custom animation builders for complete control
Performance optimized with proper disposal

🎯 Professional Theming #

Light/Dark themes with Material Design colors
Gradient themes with custom color schemes
Glass morphism with blur effects
Minimal themes for clean designs
Professional themes with shadows and animations
Custom responsive themes with breakpoint configurations
Advanced styling with custom decorations and transforms

🔧 Advanced Customization #

Custom builders for complete UI control
Advanced styling with custom borders, shapes, and transforms
Custom constraints and sizing options
Custom decorations and foreground decorations
Imperative controller API (start/pause/resume/reset/seek)
Built-in localisation (en, es, fr) with delegate
Semantic labels for accessibility
Custom time formatters and unit labels
Low time warnings with custom thresholds

🎮 Enhanced Interactions #

Haptic feedback for better UX
Vibration feedback (platform support)
Sound notifications (audio plugin integration)
Auto-hide when timer finishes
Progress tracking with percentage display
State management with ChangeNotifier provider
Error handling and validation

📊 Professional Features #

Multiple time formats: HH:MM:SS, MM:SS, SS, milliseconds
Smart formatting: Automatic format selection
Progress calculation: Built-in progress tracking
Duration extensions: Convenience methods and arithmetic
Responsive utilities: Device detection and sizing
Comprehensive testing: Unit and widget tests
Complete documentation: API reference and examples

🚀 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_advanced_countdown: ^1.0.3

🎯 Quick Start #

Basic Usage #

import 'package:flutter_advanced_countdown/flutter_advanced_countdown.dart';

// Simple responsive countdown timer
AdvancedCountdownTimer(
  duration: const Duration(minutes: 5),
  onFinish: () => print('Timer finished!'),
)

Professional Theme #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 2, seconds: 30),
  displayStyle: CountdownDisplayStyle.detailed,
  showControls: true,
  showReset: true,
  theme: CountdownTheme.professional(
    primaryColor: Colors.indigo,
    enableAnimations: true,
    enableShadows: true,
    enableRoundedCorners: true,
  ),
  onFinish: () => print('Timer finished!'),
)

Advanced Animations #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1, seconds: 30),
  displayStyle: CountdownDisplayStyle.circular,
  showControls: true,
  animationConfig: CountdownAnimationConfig(
    enabled: true,
    duration: const Duration(milliseconds: 500),
    curve: Curves.bounceOut,
    enablePulseAnimation: true,
    pulseThreshold: 15,
    enableShakeAnimation: true,
    enableScaleAnimation: true,
    enableFadeAnimation: true,
  ),
  onFinish: () => print('Timer finished!'),
)

🎨 Display Styles #

1. Professional Theme #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 2),
  displayStyle: CountdownDisplayStyle.detailed,
  theme: CountdownTheme.professional(
    primaryColor: Colors.indigo,
    enableAnimations: true,
    enableShadows: true,
    enableRoundedCorners: true,
  ),
)

2. Glass Morphism Theme #

Container(
  decoration: BoxDecoration(
    gradient: LinearGradient(
      colors: [Colors.purple, Colors.blue],
    ),
  ),
  child: AdvancedCountdownTimer(
    duration: const Duration(minutes: 1),
    displayStyle: CountdownDisplayStyle.circular,
    theme: CountdownTheme.glassMorphism(
      primaryColor: Colors.white,
      blurRadius: 15.0,
    ),
  ),
)

3. Digital Display #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1, seconds: 30),
  displayStyle: CountdownDisplayStyle.digital,
  showControls: true,
  theme: CountdownTheme.dark(primaryColor: Colors.cyan),
)

4. Analog Display #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 2),
  displayStyle: CountdownDisplayStyle.analog,
  showControls: true,
  theme: CountdownTheme.light(primaryColor: Colors.orange),
)

5. Progress Bar Display #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1, seconds: 45),
  displayStyle: CountdownDisplayStyle.progressBar,
  showControls: true,
  showLowTimeWarning: true,
  lowTimeWarningThreshold: 30,
  warningColor: Colors.red,
  theme: CountdownTheme.light(primaryColor: Colors.green),
)

6. Floating Display #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1),
  displayStyle: CountdownDisplayStyle.floating,
  showControls: true,
  theme: CountdownTheme.gradient(
    colors: [Colors.pink, Colors.purple],
    textColor: Colors.white,
  ),
)

7. Notification Display #

AdvancedCountdownTimer(
  duration: const Duration(seconds: 45),
  displayStyle: CountdownDisplayStyle.notification,
  showControls: true,
  theme: CountdownTheme.light(primaryColor: Colors.red),
)

⚡ Advanced Animations #

Custom Animation Configuration #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1, seconds: 30),
  animationConfig: CountdownAnimationConfig(
    enabled: true,
    duration: const Duration(milliseconds: 500),
    curve: Curves.bounceOut,
    enablePulseAnimation: true,
    pulseThreshold: 15,
    enableShakeAnimation: true,
    enableScaleAnimation: true,
    enableFadeAnimation: true,
  ),
)

Custom Animation Builder #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1),
  animationConfig: CountdownAnimationConfig(
    customAnimationBuilder: (child, animation) {
      return SlideTransition(
        position: Tween<Offset>(
          begin: const Offset(0, 1),
          end: Offset.zero,
        ).animate(animation),
        child: child,
      );
    },
  ),
)

🎯 Custom Builders #

Complete Custom UI #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1, seconds: 30),
  displayStyle: CountdownDisplayStyle.custom,
  customBuilderConfig: CountdownCustomBuilderConfig(
    timeBuilder: (context, remaining, isRunning, isPaused) {
      return Container(
        padding: const EdgeInsets.all(16),
        decoration: BoxDecoration(
          gradient: LinearGradient(
            colors: isRunning 
                ? [Colors.green, Colors.lightGreen]
                : [Colors.orange, Colors.deepOrange],
          ),
          borderRadius: BorderRadius.circular(12),
          boxShadow: [
            BoxShadow(
              color: Colors.black.withValues(alpha: 0.2),
              blurRadius: 8,
              offset: const Offset(0, 4),
            ),
          ],
        ),
        child: Column(
          children: [
            Icon(
              isRunning ? Icons.play_circle : Icons.pause_circle,
              color: Colors.white,
              size: 32,
            ),
            const SizedBox(height: 8),
            Text(
              remaining.formattedSmart,
              style: const TextStyle(
                fontSize: 24,
                fontWeight: FontWeight.bold,
                color: Colors.white,
              ),
            ),
            Text(
              isRunning ? 'Running' : 'Paused',
              style: const TextStyle(
                fontSize: 12,
                color: Colors.white70,
              ),
            ),
          ],
        ),
      );
    },
  ),
)

🔧 Advanced Styling #

Custom Decoration and Constraints #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 1),
  displayStyle: CountdownDisplayStyle.card,
  showControls: true,
  theme: CountdownTheme.light(primaryColor: Colors.blue).copyWith(
    width: 200,
    height: 120,
    decoration: BoxDecoration(
      gradient: const LinearGradient(
        colors: [Colors.blue, Colors.purple],
        begin: Alignment.topLeft,
        end: Alignment.bottomRight,
      ),
      borderRadius: BorderRadius.circular(16),
      boxShadow: [
        BoxShadow(
          color: Colors.blue.withValues(alpha: 0.3),
          blurRadius: 12,
          offset: const Offset(0, 6),
        ),
      ],
    ),
  ),
  advancedStyle: const CountdownAdvancedStyle(
    alignment: Alignment.center,
    semanticLabel: 'Advanced styled countdown timer',
  ),
)

📱 Responsive Design #

Device Detection #

// Get current device type
DeviceType deviceType = ResponsiveUtils.getDeviceType(context);
// Returns: DeviceType.phone, DeviceType.tablet, or DeviceType.desktop

// Get screen size category
ScreenSize screenSize = ResponsiveUtils.getScreenSize(context);
// Returns: ScreenSize.xs, ScreenSize.sm, ScreenSize.md, ScreenSize.lg, or ScreenSize.xl

Responsive Sizing #

// Get responsive font size
double fontSize = ResponsiveUtils.getResponsiveFontSize(context, base: 16.0);

// Get responsive padding
EdgeInsets padding = ResponsiveUtils.getResponsivePadding(context);

// Get responsive icon size
double iconSize = ResponsiveUtils.getResponsiveIconSize(context);

// Get responsive circular progress size
double circularSize = ResponsiveUtils.getResponsiveCircularSize(context);

Custom Responsive Theme #

AdvancedCountdownTimer(
  duration: const Duration(minutes: 2),
  displayStyle: CountdownDisplayStyle.detailed,
  showControls: true,
  useResponsiveSizing: true,
  theme: CountdownTheme.responsive(
    primaryColor: Colors.deepPurple,
    backgroundColor: Colors.deepPurple.shade50,
    textColor: Colors.deepPurple.shade900,
    fontConfig: const ResponsiveFontConfig(
      xs: 14.0,
      sm: 16.0,
      md: 18.0,
      lg: 20.0,
      xl: 22.0,
    ),
    paddingConfig: const ResponsivePaddingConfig(
      xs: EdgeInsets.all(8.0),
      sm: EdgeInsets.all(12.0),
      md: EdgeInsets.all(16.0),
      lg: EdgeInsets.all(20.0),
      xl: EdgeInsets.all(24.0),
    ),
    iconConfig: const ResponsiveIconConfig(
      xs: 16.0,
      sm: 18.0,
      md: 20.0,
      lg: 24.0,
      xl: 28.0,
    ),
    animationConfig: CountdownAnimationConfig(
      enabled: true,
      duration: const Duration(milliseconds: 300),
      curve: Curves.easeOutCubic,
      enablePulseAnimation: true,
      enableShakeAnimation: true,
      enableScaleAnimation: true,
      enableFadeAnimation: true,
    ),
  ),
  onFinish: () => print('Timer finished!'),
)

🎮 Provider Integration #

Setup Provider #

class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  final CountdownTimerProvider _provider = CountdownTimerProvider();

  @override
  void dispose() {
    _provider.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider.value(
      value: _provider,
      child: Consumer<CountdownTimerProvider>(
        builder: (context, provider, child) {
          return Column(
            children: [
              Text(
                provider.formattedTime,
                style: TextStyle(
                  fontSize: ResponsiveUtils.getResponsiveFontSize(context, base: 32.0),
                  fontWeight: FontWeight.bold,
                ),
              ),
              ElevatedButton(
                onPressed: provider.isRunning
                    ? provider.pauseTimer
                    : provider.resumeTimer,
                child: Text(provider.isRunning ? 'Pause' : 'Resume'),
              ),
            ],
          );
        },
      ),
    );
  }
}

Provider Methods #

// Start timer
provider.startTimer(
  duration: const Duration(minutes: 5),
  onFinish: () => print('Finished!'),
);

// Pause timer
provider.pauseTimer();

// Resume timer
provider.resumeTimer();

// Reset timer
provider.resetTimer();

// Get formatted time
String time = provider.formattedTime;

// Check if timer is running
bool isRunning = provider.isRunning;

📊 Responsive Breakpoints #

The package uses the following responsive breakpoints:

XS (Extra Small): < 480px (phones in portrait)
SM (Small): 480px - 768px (phones in landscape)
MD (Medium): 768px - 1024px (tablets in portrait)
LG (Large): 1024px - 1440px (tablets in landscape, small desktops)
XL (Extra Large): > 1440px (large desktops)

📱 Device Support #

✅ iPhone (all sizes)
✅ iPad (all sizes)
✅ Android Phones (all sizes)
✅ Android Tablets (all sizes)
✅ Desktop (Windows, macOS, Linux)
✅ Web (responsive web design)

🎯 Professional Features #

Enhanced User Experience #

Haptic feedback for better interaction
Vibration feedback for notifications
Sound notifications for timer completion
Auto-hide when timer finishes
Low time warnings with visual indicators
Smooth animations for state transitions

Advanced Customization #

Custom builders for complete UI control
Advanced styling with custom decorations
Custom constraints and sizing
Semantic labels for accessibility
Custom time formatters and labels
Professional themes with modern design

Performance Optimizations #

Efficient animations with proper disposal
Memory management for long-running timers
Responsive caching for performance
Minimal rebuilds with ChangeNotifier
Optimized rendering for smooth UX

🤝 Contributing #

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

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

flutter_advanced_countdown 1.0.3 flutter_advanced_countdown: ^1.0.3 copied to clipboard

Metadata