Implementing WinUI BusyIndicator

When to Use This Skill

• Display a loading indicator during background operations
• Show busy/waiting status to users during async tasks
• Indicate progress for data loading, file operations, or API calls
• Create modal or inline loading animations
• Provide visual feedback during lengthy operations
• Implement any scenario requiring "please wait" indicators

Component Overview

Syncfusion.UI.Xaml.Notifications

Syncfusion.Notifications.WinUI

Documentation and Navigation Guide

Getting Started

• Installation and NuGet package setup
• Namespace imports and basic initialization
• IsActive property for controlling visibility
• License registration requirements
• First complete example

Animation Types

• 8 built-in animation types (DottedCircularFluent, DottedCircle, DottedLinear, etc.)
• AnimationType property usage
• Visual examples and comparisons
• Choosing the right animation for your UI
• Default animation (DottedCircularFluent)

Content and Positioning

• BusyContent property for custom messages
• BusyContentPosition (Top, Bottom, Left, Right)
• BusyContentTemplate for advanced customization
• Custom DataTemplate examples
• Content display best practices

Customization Options

• SizeFactor property (adjusting indicator size)
• DurationFactor property (animation speed control)
• Color property (indicator color customization)
• Combining customization properties
• Performance considerations

Quick Start Example

<Page
    xmlns:notification="using:Syncfusion.UI.Xaml.Notifications">
    <Grid>
        <notification:SfBusyIndicator 
            x:Name="busyIndicator"
            IsActive="True"
            AnimationType="DottedCircularFluent"
            BusyContent="Loading..."
            BusyContentPosition="Bottom"
            Color="DodgerBlue"
            SizeFactor="0.5"/>
    </Grid>
</Page>

using Syncfusion.UI.Xaml.Notifications;

// Create and configure BusyIndicator
SfBusyIndicator busyIndicator = new SfBusyIndicator
{
    IsActive = true,
    AnimationType = BusyIndicatorAnimationType.DottedCircularFluent,
    BusyContent = "Loading...",
    BusyContentPosition = BusyIndicatorContentPosition.Bottom,
    Color = new SolidColorBrush(Colors.DodgerBlue),
    SizeFactor = 0.5
};

// Add to UI
this.Content = busyIndicator;

Common Patterns

1. Simple Loading Indicator

<notification:SfBusyIndicator 
    IsActive="True"
    BusyContent="Loading..."/>

2. Async Data Loading with Code-Behind

<Grid>
    <notification:SfBusyIndicator 
        x:Name="busyIndicator"
        IsActive="{x:Bind ViewModel.IsLoading, Mode=OneWay}"
        AnimationType="DottedCircle"
        BusyContent="Loading data..."/>
</Grid>

private async void LoadDataAsync()
{
    busyIndicator.IsActive = true;
    
    try
    {
        await FetchDataFromApiAsync();
    }
    finally
    {
        busyIndicator.IsActive = false;
    }
}

3. Custom Animation with Content

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="LinearFluent"
    BusyContent="Please wait..."
    BusyContentPosition="Top"
    Color="OrangeRed"
    SizeFactor="0.7"/>

4. Modal Overlay Loading Screen

<Grid>
    <!-- Main content -->
    <StackPanel>
        <TextBlock Text="Application Content"/>
        <!-- Other UI elements -->
    </StackPanel>
    
    <!-- Overlay BusyIndicator -->
    <Grid x:Name="loadingOverlay" 
          Background="#80000000"
          Visibility="{x:Bind IsProcessing, Mode=OneWay}">
        <notification:SfBusyIndicator 
            IsActive="True"
            AnimationType="DoubleCircle"
            BusyContent="Processing..."
            Color="White"/>
    </Grid>
</Grid>

5. Custom Content Template

<notification:SfBusyIndicator IsActive="True" AnimationType="DottedCircle">
    <notification:SfBusyIndicator.BusyContentTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Spacing="10">
                <TextBlock Text="⏳" FontSize="24"/>
                <TextBlock Text="Loading data..." 
                          FontSize="16" 
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </notification:SfBusyIndicator.BusyContentTemplate>
</notification:SfBusyIndicator>

6. Slow Animation for Subtle Feedback

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="SingleCircle"
    DurationFactor="0.9"
    SizeFactor="0.3"
    Color="Gray"/>

Key Properties

IsActive

true

false

AnimationType

BusyContent

BusyContentPosition

BusyContentTemplate

SizeFactor

DurationFactor

Color

Common Use Cases

Data Loading Scenarios

• Fetching data from REST APIs or databases
• Loading large datasets into grids or lists
• Refreshing dashboard content
• Initializing application data on startup

File Operations

• Uploading/downloading files
• Reading/writing large files
• Importing/exporting data
• Processing documents

Long-Running Calculations

• Complex data analysis
• Report generation
• Image processing
• Search operations

Background Tasks

• Synchronization operations
• Cache updates
• Background service communication
• Scheduled tasks

Implementation Tips

1. Binding IsActive: Use data binding to ViewModel boolean properties for clean MVVM patterns.
2. Overlay Pattern: For modal loading, use a Grid with semi-transparent background containing the BusyIndicator.
3. Performance: BusyIndicator animations are GPU-accelerated. No performance concerns for multiple instances.
4. Accessibility: The control automatically handles accessibility features. Custom content should include proper accessibility properties.
5. Threading: Always activate/deactivate BusyIndicator on the UI thread. Use

   DispatcherQueue

   if updating from background threads.
6. User Experience:
   • Show BusyIndicator immediately for operations expected to take >500ms
   • Always hide when operation completes (use try-finally blocks)
   • Position content appropriately for the UI context
   • Choose animation types that match your app's design language

Related Documentation

• Animation Types: See references/animation-types.md for detailed comparison of all 8 animation styles
• Content Customization: See references/content.md for template examples and positioning strategies
• Customization: See references/customization.md for size, speed, and color options