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.

Flutter Animated Circle Showcase

🎯 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.

Property	Type	Default	Description
`circlePainterConfig`	`CirclePainterConfig`	required	Configuration for circle appearance and segments
`scrollController`	`ScrollController?`	`null`	Enables scroll-triggered animation when provided
`onAnimationCompleted`	`VoidCallback?`	`null`	Callback fired when animation completes
`duration`	`Duration`	`600ms`	Duration of the circle drawing animation
`fadeInDuration`	`Duration`	`200ms`	Duration of fade-in effect
`curve`	`Curve`	`Curves.easeIn`	Animation curve for drawing animation
`strokeWidth`	`double`	`16.0`	Width of circle's inner stroke
`borderWidth`	`double`	`20.0`	Width of circle's outer border

AnimatedPieChartView #

The main widget for displaying animated filled pie charts.

Property	Type	Default	Description
`pieChartPainterConfig`	`PieChartPainterConfig`	required	Configuration for pie chart data and appearance
`scrollController`	`ScrollController?`	`null`	Enables scroll-triggered animation when provided
`onAnimationCompleted`	`VoidCallback?`	`null`	Callback fired when animation completes
`duration`	`Duration`	`1200ms`	Duration of the pie chart drawing animation
`fadeInDuration`	`Duration`	`300ms`	Duration of fade-in effect
`curve`	`Curve`	`Curves.easeInOut`	Animation curve for drawing animation

CirclePainterConfig #

Configuration class that defines the visual appearance of circles.

CirclePainterConfig.full()

Creates a single-color circle configuration.

Parameter	Type	Default	Description
`fillColor`	`Color`	required	Color of the circle's fill
`borderColor`	`Color`	required	Color of the circle's border
`strokeWidth`	`double`	`16.0`	Width of the inner stroke
`borderWidth`	`double`	`20.0`	Width of the outer border
`baseColor`	`Color`	`Colors.transparent`	Background color

CirclePainterConfig.segmented()

Creates a multi-segment circle configuration.

Parameter	Type	Default	Description
`segments`	`Iterable<CircleSegment>`	required	List of circle segments
`strokeWidth`	`double`	`16.0`	Width of segment strokes
`borderWidth`	`double`	`20.0`	Width of segment borders
`baseColor`	`Color`	`Colors.transparent`	Background color
`separatorAngle`	`double`	`0.18`	Angle between segments (radians)

CircleSegment #

Defines individual segments in a multi-segment circle.

Property	Type	Description
`fillColor`	`Color`	Color of the segment's fill
`borderColor`	`Color`	Color of the segment's border
`ratio`	`double`	Portion of circle (0.0 to 1.0)

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

PieChartPainterConfig #

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

Parameter	Type	Default	Description
`data`	`List<PieData>`	required	List of pie data entries defining values and colors
`strokeWidth`	`double`	`2.0`	Width of stroke outline around slices
`strokeColor`	`Color`	`Colors.white`	Color of stroke outline around slices
`separatorAngle`	`double`	`0.02`	Angle between slices (radians)
`startAngle`	`double`	`-π/2`	Starting angle for first slice (12 o'clock)

PieData #

Defines individual data entries in a pie chart.

Property	Type	Description
`value`	`double`	Numeric value (must be non-negative)
`color`	`Color`	Fill color of the pie slice
`label`	`String?`	Optional label for legends/tooltips

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 #

Fork the repository

Clone your fork:

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

Install dependencies:

flutter pub get
cd example && flutter pub get

Run tests:
```
flutter test
```
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 💙

flutter_animated_circle 0.1.1 flutter_animated_circle: ^0.1.1 copied to clipboard

Metadata