Flutter Animated Circle

A production-ready Flutter package that provides beautiful, customizable animated circular widgets with smooth animations and extensive configuration options. Perfect for creating progress indicators, pie charts, data visualizations, and engaging UI elements.

🎯 Key Features

• 🎨 Full Circle Animation: Smooth, customizable circular progress indicators with configurable timing
• 📊 Segmented Circles: Multi-colored segments ideal for pie charts, data visualization, and progress tracking
• 🥧 Animated Pie Charts: Filled pie chart slices with sequential animation and customizable styling
• 🔄 Scroll-Triggered Animation: Intelligent viewport detection with automatic animation triggering
• ⚙️ Extensive Customization: Granular control over colors, stroke widths, borders, spacing, and timing
• 🚀 Performance Optimized: Efficient rendering with RepaintBoundary and optimized painters
• 📱 Cross-Platform: Full support for Android, iOS, Web, Windows, macOS, and Linux
• 🎭 Animation Curves: Support for all Flutter animation curves and custom easing functions

🚀 Getting Started

Installation

Add flutter_animated_circle to your pubspec.yaml:

dependencies:
  flutter_animated_circle: ^0.1.0

Then run:

flutter pub get

Import

import 'package:flutter_animated_circle/flutter_animated_circle.dart';

📖 Usage Examples

Basic Usage

Simple Progress Circle

AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.full(
    fillColor: Colors.blue,
    borderColor: Colors.blue.shade800,
    strokeWidth: 16.0,
    borderWidth: 20.0,
  ),
  duration: const Duration(milliseconds: 800),
)

Multi-Segment Data Visualization

AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.segmented(
    segments: [
      CircleSegment(
        fillColor: Colors.blue, 
        borderColor: Colors.blue.shade800,
        ratio: 0.6, // 60% of the circle
      ),
      CircleSegment(
        fillColor: Colors.green, 
        borderColor: Colors.green.shade800,
        ratio: 0.4, // 40% of the circle
      ),
    ],
    strokeWidth: 16.0,
    borderWidth: 20.0,
  ),
  duration: const Duration(milliseconds: 800),
)

Filled Pie Chart

AnimatedPieChartView(
  pieChartPainterConfig: PieChartPainterConfig(
    data: [
      PieData(value: 35, color: Colors.blue, label: 'Technology'),
      PieData(value: 25, color: Colors.green, label: 'Finance'),
      PieData(value: 20, color: Colors.orange, label: 'Healthcare'),
      PieData(value: 12, color: Colors.purple, label: 'Education'),
      PieData(value: 8, color: Colors.red, label: 'Other'),
    ],
    strokeWidth: 2.0,
    separatorAngle: 0.02,
  ),
  duration: const Duration(milliseconds: 1500),
)

Advanced Features

Scroll-Triggered Animation

Automatically animate circles when they become visible during scrolling:

class ScrollableCircles extends StatefulWidget {
  @override
  State<ScrollableCircles> createState() => _ScrollableCirclesState();
}

class _ScrollableCirclesState extends State<ScrollableCircles> {
  final ScrollController _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      controller: _scrollController,
      itemCount: 10,
      itemBuilder: (context, index) {
        return Container(
          height: 400,
          padding: const EdgeInsets.all(20),
          child: AnimatedCircleView(
            circlePainterConfig: CirclePainterConfig.full(
              fillColor: Colors.amber,
              borderColor: Colors.amber.shade800,
            ),
            scrollController: _scrollController,
            duration: const Duration(milliseconds: 600),
            onAnimationCompleted: () {
              print('Circle $index animation completed!');
            },
          ),
        );
      },
    );
  }

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

Scroll-Triggered Pie Charts

class ScrollablePieCharts extends StatefulWidget {
  @override
  State<ScrollablePieCharts> createState() => _ScrollablePieChartsState();
}

class _ScrollablePieChartsState extends State<ScrollablePieCharts> {
  final ScrollController _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      controller: _scrollController,
      itemCount: 5,
      itemBuilder: (context, index) {
        return Container(
          height: 400,
          padding: const EdgeInsets.all(20),
          child: AnimatedPieChartView(
            pieChartPainterConfig: PieChartPainterConfig(
              data: [
                PieData(value: 40, color: Colors.blue.shade400),
                PieData(value: 30, color: Colors.green.shade400),
                PieData(value: 20, color: Colors.orange.shade400),
                PieData(value: 10, color: Colors.purple.shade400),
              ],
            ),
            scrollController: _scrollController,
            duration: const Duration(milliseconds: 1200),
            onAnimationCompleted: () {
              print('Pie chart $index animation completed!');
            },
          ),
        );
      },
    );
  }

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

Complex Multi-Segment Circle with Custom Styling

AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.segmented(
    segments: [
      CircleSegment(
        fillColor: Colors.red.shade400, 
        borderColor: Colors.red.shade700, 
        ratio: 0.25
      ),
      CircleSegment(
        fillColor: Colors.blue.shade400, 
        borderColor: Colors.blue.shade700, 
        ratio: 0.25
      ),
      CircleSegment(
        fillColor: Colors.green.shade400, 
        borderColor: Colors.green.shade700, 
        ratio: 0.25
      ),
      CircleSegment(
        fillColor: Colors.purple.shade400, 
        borderColor: Colors.purple.shade700, 
        ratio: 0.25
      ),
    ],
    separatorAngle: 0.05, // 5-degree gaps between segments
    baseColor: Colors.grey.shade200, // Background color
    strokeWidth: 18.0,
    borderWidth: 22.0,
  ),
  duration: const Duration(milliseconds: 1200),
  fadeInDuration: const Duration(milliseconds: 300),
  curve: Curves.easeInOutCubic,
  onAnimationCompleted: () {
    print("Multi-segment animation completed!");
  },
)

📋 API Reference

AnimatedCircleView

The main widget for displaying animated circles.

AnimatedPieChartView

The main widget for displaying animated filled pie charts.

CirclePainterConfig

Configuration class that defines the visual appearance of circles.

CirclePainterConfig.full()

Creates a single-color circle configuration.

CirclePainterConfig.segmented()

Creates a multi-segment circle configuration.

CircleSegment

Defines individual segments in a multi-segment circle.

Important: The sum of all segment ratios must equal 1.0.

PieChartPainterConfig

Configuration class that defines the visual appearance and data for pie charts.

PieData

Defines individual data entries in a pie chart.

Note: Pie slice proportions are automatically calculated based on the ratio of each value to the total sum.

🎨 Design Patterns & Use Cases

Progress Indicators

// Simple progress bar alternative
AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.full(
    fillColor: Theme.of(context).primaryColor,
    borderColor: Theme.of(context).primaryColor.withOpacity(0.3),
  ),
)

Data Visualization

// Segmented circle for statistics
AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.segmented(
    segments: [
      CircleSegment(fillColor: Colors.blue, borderColor: Colors.blue.shade700, ratio: 0.45),   // 45%
      CircleSegment(fillColor: Colors.green, borderColor: Colors.green.shade700, ratio: 0.30), // 30%
      CircleSegment(fillColor: Colors.orange, borderColor: Colors.orange.shade700, ratio: 0.25), // 25%
    ],
  ),
)

// Filled pie chart for data representation
AnimatedPieChartView(
  pieChartPainterConfig: PieChartPainterConfig(
    data: [
      PieData(value: 450, color: Colors.blue, label: 'Sales'),
      PieData(value: 300, color: Colors.green, label: 'Marketing'),
      PieData(value: 250, color: Colors.orange, label: 'Development'),
    ],
    strokeWidth: 1.5,
    separatorAngle: 0.01,
  ),
)

Loading Indicators

// Elegant loading spinner
AnimatedCircleView(
  circlePainterConfig: CirclePainterConfig.full(
    fillColor: Colors.blue.withOpacity(0.7),
    borderColor: Colors.blue,
    strokeWidth: 8.0,
    borderWidth: 12.0,
  ),
  duration: const Duration(milliseconds: 1000),
  curve: Curves.easeInOut,
)

🔧 Performance Considerations

• Efficient Rendering: Uses RepaintBoundary for optimized painting
• Memory Management: Automatic cleanup of animation controllers and listeners
• Viewport Optimization: Scroll-triggered animations only activate when visible

🐛 Troubleshooting

Common Issues

Segments don't add up to full circle

// ❌ This will throw an assertion error
CirclePainterConfig.segmented(
  segments: [
    CircleSegment(ratio: 0.5, ...),
    CircleSegment(ratio: 0.3, ...), // Total = 0.8, not 1.0
  ],
);

// ✅ Correct usage
CirclePainterConfig.segmented(
  segments: [
    CircleSegment(ratio: 0.7, ...),
    CircleSegment(ratio: 0.3, ...), // Total = 1.0
  ],
);

Animation not triggering with scroll controller

• Ensure the ScrollController is properly attached to your scrollable widget
• Check that the circle widget is actually within the scrollable area
• Verify that at least 30% of the circle is visible before animation triggers

Performance issues with many circles

• Use RepaintBoundary around individual circles when rendering many
• Consider using ListView.builder instead of ListView for better performance
• Implement lazy loading for large datasets

📱 Example App

This package includes a comprehensive example application demonstrating all features:

cd example
flutter run

The example showcases:

• Full Circle Demo: Basic circular progress indicators
• Segmented Circle Demo: Multi-colored data visualization with stroke-based segments
• Pie Chart Demo: Filled pie charts with multiple styling options
• Scroll Demo: Scroll-triggered animations for both circles and pie charts
• Performance Demo: Multiple animated components with optimized rendering

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/yourusername/flutter_animated_circle.git
   cd flutter_animated_circle
   

3. Install dependencies:

   flutter pub get
   cd example && flutter pub get
   

4. Run tests:

   flutter test
   

5. Run the example:

   cd example && flutter run
   

Code Quality

This project maintains high code quality standards:

• Linting: Uses very_good_analysis for strict code analysis
• Testing: Comprehensive test coverage for all components
• Documentation: Extensive inline documentation and examples
• Type Safety: Full null safety support

🔄 Migration Guide

From v0.0.3 to v0.1.0

No breaking changes. This release adds major new functionality:

• New Feature: AnimatedPieChartView widget for filled pie charts
• New Model: PieData class for representing pie chart data
• New Painter: PieChartPainterConfig and PieChartPainter for pie chart rendering
• Enhanced example app with pie chart demonstrations
• Comprehensive test coverage for new components
• Updated documentation with pie chart examples

From v0.0.2 to v0.0.3

No breaking changes. Previous release added:

• Enhanced documentation
• Additional usage examples
• Performance improvements
• Better error handling

📊 Changelog

See CHANGELOG.md for a detailed list of changes in each version.

📄 License

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

Made with Flutter 💙