Control.MauiCircularProgressView.Net 1.0.0

Circular Progress Bar for .NET MAUI

A beautiful, highly customizable circular progress bar control for .NET MAUI applications with multiple shape options, custom colors, and smooth rendering.

Icon

Banner

✨ Features

• 🎨 Three Shape Options: Circular (360°), Arch (180° semi-circle), and Flat (horizontal bar)
• 🎯 Fully Customizable: Colors, sizes, thickness, and edge styles
• 📊 Custom Max Values: Not limited to percentages - use any range (e.g., 250/500, 9700/15000)
• 💫 Smooth Rendering: Built with .NET MAUI Graphics for optimal performance
• 👁️ Show/Hide Text: Toggle progress display on/off
• 🔄 Edge Styles: Choose between rounded (LineCap.Round) or flat (LineCap.Butt) edges
• 📱 Cross-Platform: Works on iOS, Android, Windows, and macOS
• 🎭 Multi-Layer Support: Stack multiple progress bars for complex visualizations (donut charts)
• 🔗 MVVM Ready: Full data binding support for all properties
• 📖 Well Documented: Comprehensive XML documentation for IntelliSense

📦 Installation

Package Manager Console

Install-Package Maui.CircularProgress.Net

.NET CLI

dotnet add package Maui.CircularProgress.Net

Visual Studio

1. Right-click on your project → Manage NuGet Packages
2. Search for "Maui.CircularProgress.Net"
3. Click Install

🚀 Quick Start

1. Add Namespace to XAML

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="clr-namespace:Maui.CircularProgress.Net.Controls;assembly=Maui.CircularProgress.Net"
             x:Class="YourApp.MainPage">
    
    
    
</ContentPage>

2. Use the Control

<controls:CircularProgressBar
    Progress="75"
    MaxProgress="100"
    ProgressColor="Green"
    ProgressLeftColor="LightGreen"
    Size="140"
    TextColor="DarkGreen"
    Thickness="10"
    ShowText="True"
    ProgressEdgeShape="Round"
    Shape="Circular" />

That's it! You now have a beautiful circular progress bar displaying "75/100".

📚 Properties Reference

🎨 Shape Options

Circular (360° Full Circle)

Perfect for general progress tracking, loading indicators, and percentage displays.

<controls:CircularProgressBar
    Progress="65"
    Shape="Circular"
    ProgressColor="#6B4EFF"
    ProgressLeftColor="#E0E7FF"
    Size="150"
    Thickness="12"
    ProgressEdgeShape="Round" />

Arch (180° Semi-Circle)

Ideal for gauges, speedometers, and dashboard displays.

<controls:CircularProgressBar
    Progress="45"
    Shape="Arch"
    ProgressColor="#FB923C"
    ProgressLeftColor="#FED7AA"
    Size="150"
    Thickness="13"
    ProgressEdgeShape="Round" />

Flat (Horizontal Bar)

Great for linear progress tracking, downloads, and uploads.

<controls:CircularProgressBar
    Progress="80"
    Shape="Flat"
    ProgressColor="#10B981"
    ProgressLeftColor="#D1FAE5"
    Size="200"
    Thickness="20" />

💡 Common Use Cases

Basic Percentage Progress

<controls:CircularProgressBar
    Progress="75"
    ProgressColor="#3B82F6"
    ProgressLeftColor="#DBEAFE"
    Size="120"
    Thickness="10"
    ProgressEdgeShape="Round" />

Displays: 75/100

Custom Range Progress

<controls:CircularProgressBar
    Progress="250"
    MaxProgress="500"
    ProgressColor="#8B5CF6"
    ProgressLeftColor="#EDE9FE"
    Size="140"
    Thickness="12" />

Displays: 250/500

Progress Without Text

<controls:CircularProgressBar
    Progress="90"
    ShowText="False"
    ProgressColor="#EF4444"
    ProgressLeftColor="#FEE2E2"
    Size="100"
    Thickness="8" />

Multi-Layer Donut Chart

Create beautiful data visualizations by overlaying multiple progress bars:

<Grid WidthRequest="200" HeightRequest="200">
    
    
    <controls:CircularProgressBar
        Progress="9700"
        MaxProgress="15000"
        ProgressColor="#6B4EFF"
        ProgressLeftColor="#EDD9FA"
        Size="200"
        Thickness="25"
        ShowText="False"
        ProgressEdgeShape="Round"
        HorizontalOptions="Center"
        VerticalOptions="Center" />
    
    
    <controls:CircularProgressBar
        Progress="5300"
        MaxProgress="15000"
        ProgressColor="#FB923C"
        ProgressLeftColor="#FCC99F"
        Size="150"
        Thickness="20"
        ShowText="False"
        ProgressEdgeShape="Round"
        HorizontalOptions="Center"
        VerticalOptions="Center" />
    
    
    <VerticalStackLayout VerticalOptions="Center" HorizontalOptions="Center">
        <Label Text="Total" FontSize="12" HorizontalTextAlignment="Center" />
        <Label Text="15000" FontSize="18" FontAttributes="Bold" HorizontalTextAlignment="Center" />
    </VerticalStackLayout>
    
</Grid>

🔗 Data Binding with MVVM

ViewModel

using System.ComponentModel;
using System.Runtime.CompilerServices;

public class DashboardViewModel : INotifyPropertyChanged
{
    private int _currentProgress = 65;
    private int _maxProgress = 100;

    public int CurrentProgress
    {
        get => _currentProgress;
        set
        {
            _currentProgress = value;
            OnPropertyChanged();
        }
    }

    public int MaxProgress
    {
        get => _maxProgress;
        set
        {
            _maxProgress = value;
            OnPropertyChanged();
        }
    }

    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

XAML

<controls:CircularProgressBar
    Progress="{Binding CurrentProgress}"
    MaxProgress="{Binding MaxProgress}"
    ProgressColor="#10B981"
    ProgressLeftColor="#D1FAE5"
    Size="150"
    Thickness="12" />

🎨 Pre-built Color Themes

Success Theme (Green)

<controls:CircularProgressBar
    Progress="85"
    ProgressColor="#10B981"
    ProgressLeftColor="#D1FAE5"
    TextColor="#065F46" />

Warning Theme (Orange)

<controls:CircularProgressBar
    Progress="60"
    ProgressColor="#F59E0B"
    ProgressLeftColor="#FEF3C7"
    TextColor="#92400E" />

Danger Theme (Red)

<controls:CircularProgressBar
    Progress="30"
    ProgressColor="#EF4444"
    ProgressLeftColor="#FEE2E2"
    TextColor="#991B1B" />

Info Theme (Blue)

<controls:CircularProgressBar
    Progress="50"
    ProgressColor="#3B82F6"
    ProgressLeftColor="#DBEAFE"
    TextColor="#1E40AF" />

📱 Platform Support

🔧 Advanced Features

Dynamic Progress Updates

public async Task AnimateProgress()
{
    for (int i = 0; i <= 100; i += 5)
    {
        MyProgressBar.Progress = i;
        await Task.Delay(50); // 50ms delay
    }
}

Conditional Color Changes

public void UpdateProgressColor(int progress)
{
    if (progress < 30)
        MyProgressBar.ProgressColor = Colors.Red;
    else if (progress < 70)
        MyProgressBar.ProgressColor = Colors.Orange;
    else
        MyProgressBar.ProgressColor = Colors.Green;
}

📖 Documentation

• Complete Usage Examples
• API Reference
• Change Log

🐛 Troubleshooting

Progress bar not visible

• Ensure the Size property is set (default is 100)
• Check that the parent container has enough space
• Verify colors aren't matching the background

Text not displaying

• Check that ShowText is set to true (default)
• Verify TextColor contrasts with the background
• Ensure Size is large enough (minimum 80 recommended for text)

Colors not applying

• Use proper color formats: Colors.Blue or Color.FromArgb("#3B82F6")
• Check for typos in color names

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

• Built with .NET MAUI
• Powered by .NET MAUI Graphics
• Inspired by modern UI/UX design principles
• Thanks to the .NET MAUI community for feedback and support

⭐ Show Your Support

If you find this library helpful, please consider:

• ⭐ Giving it a star on GitHub
• 📢 Sharing it with others
• 🐛 Reporting bugs or requesting features
• 🤝 Contributing to the project

📊 Stats

Made with ❤️ for the .NET MAUI community

Happy coding! 🚀