Syncfusion Blazor Progress Bar

Implementing Syncfusion Blazor ProgressBar

When to Use This Skill

Use this skill when the user needs to:

• Display progress for file uploads, downloads, or data processing
• Show loading states with determinate or indeterminate progress
• Visualize task completion percentages
• Implement buffer states for media players or streaming content
• Create circular or linear progress indicators
• Add progress tracking with custom styling and animations
• Show multi-stage progress with segments
• Implement accessible progress indicators with WCAG compliance
• Display progress with annotations, labels, or custom formatting

Component Overview

The Syncfusion Blazor ProgressBar component is a visual indicator that displays the progress of an operation. It supports both linear and circular types, multiple states (determinate, indeterminate, buffer, active, striped), extensive customization options, animations, and full accessibility support.

API Reference

📄 Read: references/api-reference.md

Use this reference when you need the exact ProgressBar API surface, including:

• SfProgressBar properties such as Value, Type, Role, Theme, Visible, ID, StartAngle, EndAngle, and RefreshAsync()
• Child components such as ProgressBarAnimation, ProgressBarEvents, ProgressBarAnnotations, ProgressBarAnnotation, ProgressBarLabelStyle, ProgressBarMargin, ProgressBarRangeColor, and ProgressBarRangeColors
• Event callbacks such as ValueChanged, ProgressCompleted, AnimationComplete, AnnotationRender, TextRender, and Loaded
• Enums such as ProgressType, CornerType, ModeType, and TextAlignmentType

Key Capabilities:

• Types: Linear (horizontal bar) and Circular (donut/pie chart style)
• States: Determinate (known progress), Indeterminate (unknown progress), Buffer (dual progress), Active (animated), Striped (visual pattern)
• Customization: Colors, thickness, segments, radius, corners, margins, RTL support
• Features: Annotations, labels, range colors, gradients, secondary progress
• Animation: Configurable speed and delay
• Events: Value changes, completion, animation lifecycle
• Accessibility: WCAG 2.2 compliant with keyboard navigation

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

When the user needs to set up the ProgressBar for the first time, guide them to this reference for:

• Prerequisites and system requirements
• Installation via Visual Studio, VS Code, or .NET CLI
• NuGet package installation (Syncfusion.Blazor.ProgressBar)
• Namespace imports and service registration
• Adding stylesheet and script references
• Basic linear and circular ProgressBar implementation
• First working example

Types and Modes

📄 Read: references/types-and-modes.md

When the user asks about or needs:

• Linear vs Circular ProgressBar types
• Choosing the right type for their use case
• Implementing basic linear progress bars
• Implementing circular/donut progress bars
• Pie progress mode for circular bars
• Segments in linear or circular types
• Secondary progress indicators
• Complete type-specific examples

States and Behavior

📄 Read: references/states-and-behavior.md

When the user asks about or needs:

• Determinate progress (known completion percentage)
• Indeterminate progress (loading without known duration)
• Buffer state (dual progress for media/streaming)
• Active state (animated progress indicator)
• Striped visual pattern (linear only)
• Range configuration (Minimum/Maximum values)
• Combining multiple states
• Choosing the right state for their scenario

Customization

📄 Read: references/customization.md

When the user asks about or needs:

• Dividing progress into segments with custom colors
• Adjusting track, progress, or secondary progress thickness
• Customizing radius and inner radius (circular)
• Rounded corners (CornerRadius)
• Custom colors for progress, track, and secondary progress
• Range colors with gradient effects
• RTL (right-to-left) support
• Visibility control (showing/hiding progress bar)
• Margin and spacing adjustments
• Complete visual customization examples

Annotations and Labels

📄 Read: references/annotations-and-labels.md

When the user asks about or needs:

• Adding text annotations to the progress bar
• Custom HTML or component overlays
• Showing progress percentage labels
• Custom label formatting (TextRender event)
• Positioning annotations
• Multiple annotations
• Styling annotations and labels
• Combining annotations with labels

Animation

📄 Read: references/animation.md

When the user asks about or needs:

• Enabling progress animations
• Controlling animation speed (Duration)
• Adding animation delays
• Animation with different states
• AnimationComplete event handling
• Performance considerations
• Smooth progress transitions

Events and Accessibility

📄 Read: references/events-and-accessibility.md

When the user asks about or needs:

• ValueChanged event (tracking progress changes)
• ProgressCompleted event (when progress reaches maximum)
• AnimationComplete event (animation lifecycle)
• AnnotationRender event (customizing annotations)
• TextRender event (custom label formatting)
• Loaded event (component initialization)
• WCAG 2.2 and Section 508 compliance
• Keyboard navigation support
• Screen reader compatibility
• Color contrast and accessibility standards
• Mobile device support

Quick Start Example

Linear ProgressBar (Basic)

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               Minimum="0" 
               Maximum="100"
               Height="60"
               TrackThickness="12" 
               ProgressThickness="12">
</SfProgressBar>

Circular ProgressBar (Basic)

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Minimum="0" 
               Maximum="100"
               Height="160px"
               Width="160px"
               TrackThickness="8" 
               ProgressThickness="8">
</SfProgressBar>

Indeterminate Loading State

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="20" 
               IsIndeterminate="true"
               Height="60"
               Minimum="0" 
               Maximum="100">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
</SfProgressBar>

Common Patterns

Pattern 1: File Upload Progress

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@uploadProgress" 
               ShowProgressValue="true"
               Height="60"
               ProgressColor="#28a745"
               TrackColor="#e9ecef"
               CornerRadius="CornerType.Round">
    <ProgressBarEvents ProgressCompleted="OnUploadComplete"></ProgressBarEvents>
</SfProgressBar>

@code {
    private double uploadProgress = 0;
    
    private void OnUploadComplete(ProgressValueEventArgs args)
    {
        // Handle upload completion
    }
}

Pattern 2: Multi-Stage Progress with Segments

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60"
               SegmentCount="4"
               SegmentColor='new string[] { "#00bdaf", "#2f7ecc", "#e9648e", "#fbb78a" }'>
</SfProgressBar>

Pattern 3: Buffer State for Media Player

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@currentProgress" 
               SecondaryProgress="@bufferProgress"
               Height="60"
               ProgressColor="#ff4081"
               SecondaryProgressColor="#ff80ab">
</SfProgressBar>

@code {
    private double currentProgress = 0;
    private double bufferProgress = 0;

    protected override void OnInitialized()
    {
        // Sample values for testing
        currentProgress = 40;   // main progress
        bufferProgress = 70;    // secondary buffer progress
    }
}

Pattern 4: Circular Progress with Annotation

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="160px" 
               Width="160px"
               TrackThickness="10" 
               ProgressThickness="10"
               ProgressColor="#e91e63">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size:24px; font-weight:bold; color:#e91e63;">
                    80%
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Key Props Reference

Core Properties

• Type: ProgressType.Linear or ProgressType.Circular - Progress bar type
• Value: Current progress value within the configured range
• Minimum: Minimum range value
• Maximum: Maximum range value
• Height: Component height
• Width: Component width
• ID: Component identifier for programmatic targeting
• ChildContent: Custom child content inside the component

State Properties

• IsIndeterminate: Enable indeterminate loading state (unknown duration)
• SecondaryProgress: Secondary progress value for buffer state
• IsActive: Enable active animated state
• IsStriped: Enable striped pattern (linear only)
• Role: Progress indication mode (ModeType.Auto, Success, Info, Danger, Warning)
• Theme: Visual theme for the ProgressBar
• EnableRtl: Right-to-left rendering support
• Visible: Show or hide the component

Customization Properties

• ProgressColor: Progress indicator color
• TrackColor: Background track color
• SecondaryProgressColor: Secondary progress color
• ProgressThickness: Progress bar thickness
• TrackThickness: Track thickness
• SecondaryProgressThickness: Secondary progress thickness
• CornerRadius: Edge rounding (CornerType.Auto, Square, Round, Round4px)
• SegmentCount: Divide progress into segments
• SegmentColor: Array of colors for segments
• EnableProgressSegments: Segments without track background
• EnablePieProgress: Circular pie-style rendering
• Radius: Circular progress radius
• InnerRadius: Circular inner radius
• GapWidth: Gap width between segments
• StartAngle: Circular start angle
• EndAngle: Circular end angle
• IsGradient: Enable gradient rendering

Display Properties

• ShowProgressValue: Show percentage label
• EnablePieProgress: Fill circular progress as pie chart

Animation Properties

Use <ProgressBarAnimation> child component:

• Enable: Enable animation
• Duration: Animation duration in milliseconds
• Delay: Animation start delay in milliseconds

Methods

• RefreshAsync(): Re-render the ProgressBar when the state changes outside the normal render flow

Common Use Cases

Use Case 1: Simple Loading Indicator

Scenario: Show a loading bar while fetching data Implementation: Use indeterminate linear progress bar with animation

Use Case 2: File Upload with Percentage

Scenario: Display file upload progress with percentage Implementation: Determinate progress with ShowProgressValue="true"

Use Case 3: Multi-Step Wizard

Scenario: Show progress through a multi-step form Implementation: Segmented progress bar with step count as segments

Use Case 4: Video Buffer State

Scenario: Show playback position and buffered content Implementation: Buffer state with primary (playback) and secondary (buffered) progress

Use Case 5: Dashboard KPI Indicator

Scenario: Circular progress showing goal completion Implementation: Circular progress with annotation showing percentage and target

Use Case 6: Download Progress with Time Estimate

Scenario: Show download progress with custom time remaining label Implementation: Linear progress with TextRender event for custom formatting

Use Case 7: Determinate Task Progress

Scenario: Show progress of a batch operation with known steps Implementation: Determinate progress bar updating Value as each step completes

Best Practices

1. Choose the Right Type:

• Use Linear for horizontal layouts, file operations, loading bars
• Use Circular for compact spaces, dashboards, goal indicators

2. Select Appropriate State:

• Determinate when you know the completion percentage
• Indeterminate for unknown duration operations
• Buffer for streaming or multi-stage loading
• Active/Striped for visual emphasis on ongoing operations

3. Provide User Feedback:

• Show percentage labels for long operations
• Use annotations for contextual information
• Handle ProgressCompleted event to notify users

4. Accessibility:

• Ensure adequate color contrast
• Don't rely solely on color to convey information
• Test with screen readers
• Support keyboard navigation

5. Performance:

• Avoid excessive Value updates (throttle updates for smooth animation)
• Use appropriate animation durations (1000-2000ms typically)
• Consider disabling animation for very frequent updates

6. Styling:

• Match your application's design system
• Use range colors for meaningful thresholds
• Ensure progress bar is visible against background
• Use appropriate thickness for the context

Troubleshooting Quick Reference

• Progress bar not visible: Check Height, Width, and color contrast with background
• Animation not working: Ensure <ProgressBarAnimation Enable="true" />
• Themes not applied: Verify stylesheet reference in index.html
• Events not firing: Check ProgressBarEvents component and method signatures
• Striped not showing: Striped only works with Linear type
• Percentage not displaying: Set ShowProgressValue="true"

For detailed setup, configuration, and advanced scenarios, navigate to the appropriate reference file above.

Animation

Table of Contents

• Overview
• Enabling Animation
• ProgressBarAnimation Configuration
• Enable Property
• Animation Properties
• Duration (Speed Control)
• Delay (Start Delay)
• Animation with Different States
• Determinate Animation
• Indeterminate Animation
• Active State Animation
• Animation Events
• AnimationComplete Event
• Coordinating with Other Events
• Performance Considerations
• Complete Examples

Overview

Animation enhances the ProgressBar by providing smooth visual transitions when progress values change or during indeterminate loading states. The ProgressBarAnimation component with Enable, Duration, and Delay properties controls all animation behavior. Properly configured animations improve user experience by:

• Providing visual feedback that something is happening
• Making progress changes appear smooth and natural
• Drawing attention to progress updates
• Indicating active processing during indeterminate states

Animation Capabilities:

• Smooth progress transitions - Animated fill from current to new value
• Indeterminate motion - Continuous movement for unknown duration operations
• Configurable speed - Control animation duration
• Delayed starts - Add initial delay before animation begins
• Completion events - Execute code when animation finishes

Enabling Animation

ProgressBarAnimation Configuration

Enable animation using the <ProgressBarAnimation> child component within <SfProgressBar>. The Enable property controls whether animation is active:

Basic Animation Setup:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="90" 
               Height="60" 
               Width="90%" 
               TrackColor="#FFFFFF" 
               ShowProgressValue="true" 
               ProgressColor="#2BB20E" 
               TrackThickness="24" 
               CornerRadius="CornerType.Round" 
               ProgressThickness="24" 
               Minimum="0" 
               Maximum="100">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="0">
    </ProgressBarAnimation>
</SfProgressBar>

Component Structure:

<SfProgressBar ...>
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="0">
    </ProgressBarAnimation>
</SfProgressBar>

Enable Property

The Enable property activates animation on the <ProgressBarAnimation> component:

Animation Enabled:

<SfProgressBar Value="75" Height="60">
    <ProgressBarAnimation Enable="true"></ProgressBarAnimation>
</SfProgressBar>

Result: Progress animates smoothly when value changes.

Animation Disabled (Default):

<SfProgressBar Value="75" Height="60">
    <!-- No animation component, or Enable="false" -->
</SfProgressBar>

Result: Progress jumps instantly to new value without animation.

Toggling Animation:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@progress" Height="60">
    <ProgressBarAnimation Enable="@animationEnabled"></ProgressBarAnimation>
</SfProgressBar>

<button @onclick="ToggleAnimation">
    @(animationEnabled ? "Disable" : "Enable") Animation
</button>

@code {
    private double progress = 50;
    private bool animationEnabled = true;
    
    private void ToggleAnimation()
    {
        animationEnabled = !animationEnabled;
    }
}

Animation Properties

Duration (Speed Control)

The Duration property on <ProgressBarAnimation> controls how long the animation takes to complete, specified in milliseconds:

Fast Animation (1 second):

<SfProgressBar Value="80" Height="60">
    <ProgressBarAnimation Enable="true" Duration="1000"></ProgressBarAnimation>
</SfProgressBar>

Normal Animation (2 seconds - Default):

<SfProgressBar Value="80" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
</SfProgressBar>

Slow Animation (4 seconds):

<SfProgressBar Value="80" Height="60">
    <ProgressBarAnimation Enable="true" Duration="4000"></ProgressBarAnimation>
</SfProgressBar>

Duration Guidelines:

Dynamic Duration Based on Change:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@currentValue" Height="60">
    <ProgressBarAnimation Enable="true" Duration="@animationDuration">
    </ProgressBarAnimation>
</SfProgressBar>

<button @onclick="SmallIncrement">+10 (Fast)</button>
<button @onclick="LargeIncrement">+50 (Slow)</button>

@code {
    private double currentValue = 0;
    private int animationDuration = 1000;
    
    private void SmallIncrement()
    {
        currentValue += 10;
        animationDuration = 500; // Fast for small changes
    }
    
    private void LargeIncrement()
    {
        currentValue += 50;
        animationDuration = 2000; // Slower for large changes
    }
}

Delay (Start Delay)

The Delay property on <ProgressBarAnimation> adds a pause before the animation starts, specified in milliseconds:

No Delay (Immediate - Default):

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="70" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="0">
    </ProgressBarAnimation>
</SfProgressBar>

500ms Delay:

<SfProgressBar Value="70" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="500">
    </ProgressBarAnimation>
</SfProgressBar>

2 Second Delay:

<SfProgressBar Value="70" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="1900">
    </ProgressBarAnimation>
</SfProgressBar>

Use Cases for Delay:

• Staggered animations (multiple progress bars start at different times)
• Wait for user to read information before animating
• Coordinated sequences with other UI elements
• Dramatic effect or emphasis

Staggered Progress Bars:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="80" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="0">
    </ProgressBarAnimation>
</SfProgressBar>

<SfProgressBar Value="60" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="500">
    </ProgressBarAnimation>
</SfProgressBar>

<SfProgressBar Value="90" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000" Delay="1000">
    </ProgressBarAnimation>
</SfProgressBar>

Result: Three progress bars animate in sequence with 500ms between each.

Animation with Different States

Determinate Animation

For determinate progress (known percentage), animation smoothly transitions from the current value to the new value using the Value property on <SfProgressBar> with <ProgressBarAnimation> enabled:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@progressValue" 
               Height="60"
               ShowProgressValue="true"
               TrackThickness="20"
               ProgressThickness="20"
               ProgressColor="#0d6efd"
               TrackColor="#e9ecef">
    <ProgressBarAnimation Enable="true" Duration="1000"></ProgressBarAnimation>
</SfProgressBar>

<button class="btn btn-primary" @onclick="UpdateProgress">Update Progress</button>

@code {
    private double progressValue = 25;
    
    private void UpdateProgress()
    {
        progressValue += 15;
        if (progressValue > 100) progressValue = 0;
    }
}

Behavior:

• Progress animates from current value (25%) to new value (40%)
• Animation takes 1000ms (1 second)
• Smooth, linear transition

Indeterminate Animation

For indeterminate progress (unknown duration), animation provides continuous movement using the IsIndeterminate property set to true with <ProgressBarAnimation> enabled:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="20" 
               Height="60" 
               IsIndeterminate="true"
               TrackThickness="16"
               ProgressThickness="16"
               ProgressColor="#6f42c1"
               TrackColor="#e9ecef">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
</SfProgressBar>

Behavior:

• Continuous, repeating animation
• Progress indicator moves across the bar repeatedly
• Duration controls the speed of each animation cycle
• Must have Enable="true" for indeterminate state to animate

Circular Indeterminate (Loading Spinner):

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="20" 
               Height="100px"
               Width="100px"
               IsIndeterminate="true"
               TrackThickness="8"
               ProgressThickness="8"
               ProgressColor="#0d6efd"
               TrackColor="#e9ecef">
    <ProgressBarAnimation Enable="true" Duration="1500"></ProgressBarAnimation>
</SfProgressBar>

Behavior:

• Rotating arc/spinner
• Duration controls rotation speed
• Faster duration (1000-1500ms) for active feel
• Slower duration (2500-3000ms) for subtle loading

Active State Animation

The IsActive property adds flowing animation to determinate progress, and can be combined with the IsStriped property for striped animation effects:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               IsActive="true" 
               Value="60" 
               Height="60"
               TrackThickness="20"
               ProgressThickness="20"
               ProgressColor="#28a745"
               TrackColor="#e9ecef">
    <ProgressBarAnimation Enable="true" Duration="1500"></ProgressBarAnimation>
</SfProgressBar>

Behavior:

• Progress fills to the value (60%)
• Flowing/shimmering effect over the filled portion
• Indicates active, ongoing operation
• Combine with IsStriped="true" for striped + active animation (Linear only)

Active + Striped:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               IsActive="true" 
               IsStriped="true"
               Value="70" 
               Height="60"
               TrackThickness="20"
               ProgressThickness="20"
               ProgressColor="#ffc107"
               TrackColor="#e9ecef">
    <ProgressBarAnimation Enable="true" Duration="1000"></ProgressBarAnimation>
</SfProgressBar>

Result: Animated striped pattern that moves/flows, creating strong visual activity.

Animation Events

AnimationComplete Event

The AnimationComplete event on <ProgressBarEvents> fires when the animation finishes, providing access to the animation state through event arguments:

Basic Usage:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
    <ProgressBarEvents AnimationComplete="@OnAnimationComplete"></ProgressBarEvents>
</SfProgressBar>

<p>@statusMessage</p>

@code {
    private string statusMessage = "";
    
    private void OnAnimationComplete(ProgressValueEventArgs args)
    {
        statusMessage = $"Animation completed at value: {args.Value}";
    }
}

Event Arguments:

• args.Value - The value when animation completed

Use Cases:

• Show completion message
• Hide progress bar after animation
• Trigger next step in a workflow
• Play sound or show notification
• Update UI state

Hide Progress Bar After Completion:

<SfProgressBar Type="ProgressType.Linear" 
               Value="@progressValue" 
               Height="60" 
               Visible="@showProgressBar"
               TrackThickness="16"
               ProgressThickness="16">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
    <ProgressBarEvents AnimationComplete="@OnAnimationComplete"></ProgressBarEvents>
</SfProgressBar>

<p style="color: green; font-weight: bold;">@completionMessage</p>

<button class="btn btn-primary" @onclick="StartProcess">Start Process</button>

@code {
    private double progressValue = 0;
    private bool showProgressBar = false;
    private string completionMessage = "";
    
    private void StartProcess()
    {
        showProgressBar = true;
        progressValue = 100;
        completionMessage = "";
    }
    
    private void OnAnimationComplete(ProgressValueEventArgs args)
    {
        if (args.Value == 100)
        {
            Task.Delay(500).ContinueWith(_ =>
            {
                InvokeAsync(() =>
                {
                    showProgressBar = false;
                    completionMessage = "✓ Process completed successfully!";
                    StateHasChanged();
                });
            });
        }
    }
}

Coordinating with Other Events

Combine AnimationComplete with other <ProgressBarEvents> like ProgressCompleted for complex workflows:

With ProgressCompleted:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@progress" Height="60">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
    <ProgressBarEvents 
        ProgressCompleted="@OnProgressCompleted"
        AnimationComplete="@OnAnimationComplete">
    </ProgressBarEvents>
</SfProgressBar>

@code {
    private double progress = 100;
    
    private void OnProgressCompleted(ProgressValueEventArgs args)
    {
        // Fires when progress reaches maximum (100)
        Console.WriteLine("Progress reached 100%");
    }
    
    private void OnAnimationComplete(ProgressValueEventArgs args)
    {
        // Fires when animation finishes
        Console.WriteLine("Animation finished");
        // If progress is 100, both events fire
    }
}

Multi-Stage Process:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@currentProgress" Height="60" ShowProgressValue="true">
    <ProgressBarAnimation Enable="true" Duration="1500"></ProgressBarAnimation>
    <ProgressBarEvents AnimationComplete="@OnStageComplete"></ProgressBarEvents>
</SfProgressBar>

<p>@statusMessage</p>

@code {
    private double currentProgress = 0;
    private string statusMessage = "Ready to start";
    private int stage = 0;
    
    protected override void OnInitialized()
    {
        StartProcess();
    }
    
    private void StartProcess()
    {
        stage = 1;
        currentProgress = 33;
        statusMessage = "Stage 1: Initializing...";
    }
    
    private void OnStageComplete(ProgressValueEventArgs args)
    {
        stage++;
        
        switch (stage)
        {
            case 2:
                currentProgress = 66;
                statusMessage = "Stage 2: Processing...";
                break;
            case 3:
                currentProgress = 100;
                statusMessage = "Stage 3: Finalizing...";
                break;
            case 4:
                statusMessage = "Complete!";
                break;
        }
    }
}

Performance Considerations

Animation Performance Tips

The Duration and Delay properties on <ProgressBarAnimation> significantly impact performance and should be selected carefully.

1. Duration Selection:

• Short animations (300-500ms): Better for frequent updates but may feel jarring
• Medium animations (1000-2000ms): Good balance for most scenarios
• Long animations (3000ms+): Use sparingly, can feel sluggish

2. Update Frequency:

@using Syncfusion.Blazor.ProgressBar

<!-- Good: Moderate update frequency -->
<SfProgressBar Value="@progress" Height="60">
    <ProgressBarAnimation Enable="true" Duration="500"></ProgressBarAnimation>
</SfProgressBar>

@code {
    private System.Threading.Timer? timer;
    private double progress = 0;
    
    protected override void OnInitialized()
    {
        // Update every 500ms matches animation duration
        timer = new System.Threading.Timer(_ =>
        {
            if (progress < 100)
            {
                progress += 10;
                InvokeAsync(StateHasChanged);
            }
        }, null, 0, 500);
    }
}

3. Disable Animation for Rapid Updates:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@progress" Height="60">
    <ProgressBarAnimation Enable="@enableAnimation"></ProgressBarAnimation>
</SfProgressBar>

@code {
    private double progress = 80;
    private bool enableAnimation = true;
    
    private void RapidUpdate()
    {
        // Disable animation for rapid, small changes
        enableAnimation = false;
        progress = 75;
        StateHasChanged();
        
        // Re-enable after stable
        Task.Delay(1000).ContinueWith(_ =>
        {
            InvokeAsync(() =>
            {
                enableAnimation = true;
                StateHasChanged();
            });
        });
    }
}

4. Indeterminate Animation:

• Uses continuous animation, minimal performance impact
• Avoid multiple indeterminate progress bars on same page
• Use shorter duration (1000-2000ms) to reduce animation overhead

5. Mobile Devices:

• Test animations on slower devices
• Consider slightly longer durations (add 500ms) for smoother appearance
• Avoid very fast animations (<500ms) that may stutter

When to Disable Animation

Set the Enable property to false on <ProgressBarAnimation> when:

Disable animation when:

• User has motion sensitivity preferences
• Very frequent updates (multiple times per second)
• Low-end devices or poor performance detected
• User explicitly disables animations in settings

Respect Motion Preferences:

@using Syncfusion.Blazor.ProgressBar
@using Microsoft.JSInterop

<SfProgressBar Value="@progress" Height="60">
    <ProgressBarAnimation Enable="@animationEnabled"></ProgressBarAnimation>
</SfProgressBar>

@code {
    [Inject] private IJSRuntime JS { get; set; }
    private double progress = 50;
    private bool animationEnabled = true;
    
    protected override async Task OnInitializedAsync()
    {
        // Check for reduced motion preference
        var prefersReducedMotion = await JS.InvokeAsync<bool>(
            "matchMedia", "(prefers-reduced-motion: reduce)");
        
        if (prefersReducedMotion)
        {
            animationEnabled = false;
        }
    }
}

Complete Examples

Example 1: Smooth File Upload

@using Syncfusion.Blazor.ProgressBar

<div style="padding: 20px;">
    <h4>Uploading: report.pdf</h4>
    
    <SfProgressBar Type="ProgressType.Linear" 
                   Value="@uploadProgress" 
                   Height="60"
                   ShowProgressValue="true"
                   TrackThickness="20"
                   ProgressThickness="20"
                   CornerRadius="CornerType.Round"
                   ProgressColor="#28a745"
                   TrackColor="#e9ecef">
        <ProgressBarAnimation Enable="true" Duration="800"></ProgressBarAnimation>
        <ProgressBarEvents AnimationComplete="@CheckCompletion"></ProgressBarEvents>
    </SfProgressBar>
    
    <p style="margin-top: 10px;">@statusMessage</p>
    <button class="btn btn-primary" @onclick="SimulateUpload" disabled="@isUploading">
        Start Upload
    </button>
</div>

@code {
    private double uploadProgress = 0;
    private bool isUploading = false;
    private string statusMessage = "Ready to upload";
    private System.Threading.Timer? timer;
    
    private void SimulateUpload()
    {
        isUploading = true;
        uploadProgress = 0;
        statusMessage = "Uploading...";
        
        timer = new System.Threading.Timer(_ =>
        {
            if (uploadProgress < 100)
            {
                uploadProgress += 10;
                InvokeAsync(StateHasChanged);
            }
            else
            {
                timer?.Dispose();
            }
        }, null, 0, 800);
    }
    
    private void CheckCompletion(ProgressValueEventArgs args)
    {
        if (args.Value >= 100)
        {
            statusMessage = "✓ Upload complete!";
            isUploading = false;
            StateHasChanged();
        }
    }
    
    public void Dispose()
    {
        timer?.Dispose();
    }
}

Example 2: Loading Spinner

@using Syncfusion.Blazor.ProgressBar

<div style="display: flex; justify-content: center; align-items: center; height: 300px;">
    <div style="text-align: center;">
        <SfProgressBar Type="ProgressType.Circular" 
                       Value="20" 
                       Height="120px"
                       Width="120px"
                       IsIndeterminate="true"
                       TrackThickness="8"
                       ProgressThickness="8"
                       ProgressColor="#0d6efd"
                       TrackColor="#e9ecef">
            <ProgressBarAnimation Enable="true" Duration="1500"></ProgressBarAnimation>
        </SfProgressBar>
        
        <p style="margin-top: 20px; font-size: 18px; color: #666;">
            Loading, please wait...
        </p>
    </div>
</div>

Example 3: Multi-Stage with Different Durations

@using Syncfusion.Blazor.ProgressBar

<div style="padding: 20px;">
    <h4>@stageName</h4>
    
    <SfProgressBar Value="@stageProgress" 
                   Height="60"
                   ShowProgressValue="true"
                   TrackThickness="18"
                   ProgressThickness="18"
                   ProgressColor="@stageColor">
        <ProgressBarAnimation Enable="true" Duration="@animationDuration">
        </ProgressBarAnimation>
        <ProgressBarEvents AnimationComplete="@OnStageAnimationComplete">
        </ProgressBarEvents>
    </SfProgressBar>
</div>

@code {
    private double stageProgress = 0;
    private int animationDuration = 2000;
    private string stageName = "Stage 1: Quick initialization";
    private string stageColor = "#0d6efd";
    
    protected override void OnInitialized()
    {
        StartStage1();
    }
    
    private void StartStage1()
    {
        stageName = "Stage 1: Quick initialization";
        stageProgress = 100;
        animationDuration = 1000; // Fast
        stageColor = "#0d6efd";
    }
    
    private void OnStageAnimationComplete(ProgressValueEventArgs args)
    {
        if (stageName.Contains("Stage 1"))
        {
            Task.Delay(500).ContinueWith(_ =>
            {
                InvokeAsync(() =>
                {
                    stageName = "Stage 2: Processing data";
                    stageProgress = 100;
                    animationDuration = 3000; // Slow for emphasis
                    stageColor = "#ffc107";
                    StateHasChanged();
                });
            });
        }
        else if (stageName.Contains("Stage 2"))
        {
            Task.Delay(500).ContinueWith(_ =>
            {
                InvokeAsync(() =>
                {
                    stageName = "Stage 3: Finalizing";
                    stageProgress = 100;
                    animationDuration = 1500; // Medium
                    stageColor = "#28a745";
                    StateHasChanged();
                });
            });
        }
    }
}

Example 4: Smooth Value Updates

@using Syncfusion.Blazor.ProgressBar

<div style="padding: 20px;">
    <SfProgressBar Value="@targetProgress" 
                   Height="60"
                   ShowProgressValue="true"
                   TrackThickness="20"
                   ProgressThickness="20"
                   CornerRadius="CornerType.Round">
        <ProgressBarAnimation Enable="true" Duration="1200"></ProgressBarAnimation>
    </SfProgressBar>
    
    <div style="margin-top: 20px;">
        <button class="btn btn-secondary" @onclick="() => SetProgress(25)">25%</button>
        <button class="btn btn-secondary" @onclick="() => SetProgress(50)">50%</button>
        <button class="btn btn-secondary" @onclick="() => SetProgress(75)">75%</button>
        <button class="btn btn-secondary" @onclick="() => SetProgress(100)">100%</button>
    </div>
</div>

@code {
    private double targetProgress = 0;
    
    private void SetProgress(double value)
    {
        targetProgress = value;
    }
}

Animation is a powerful feature that enhances user experience when properly configured. Match animation duration to the frequency and magnitude of progress updates for optimal results.

Annotations and Labels

Table of Contents

• Overview
• Annotations
• What Are Annotations
• ProgressBarAnnotations Setup
• ContentTemplate Usage
• Adding Text Annotations
• Adding Custom HTML/Components
• Positioning Annotations
• Multiple Annotations
• Styling Annotations
• Labels (ShowProgressValue)
• Enabling Progress Labels
• Default Percentage Format
• Custom Text Formatting
• TextRender Event
• Label Positioning
• Combining Annotations and Labels
• Complete Examples
• Best Practices

Overview

Annotations and labels enhance progress bars by displaying contextual information directly on or near the progress indicator. This improves usability by providing immediate visual feedback without requiring users to look elsewhere.

Key Features:

• Annotations: Custom content overlaid on the progress bar (text, HTML, components)
• Labels: Built-in progress percentage display with customizable formatting
• Both work with Linear and Circular types
• Fully customizable styling and positioning

When to Use:

• Annotations: Display custom information (time remaining, status messages, icons, complex layouts)
• Labels: Show simple progress percentage or custom numeric values

Annotations

What Are Annotations

Annotations are custom content elements created using the ProgressBarAnnotation and ContentTemplate properties that overlay the progress bar, typically centered within circular progress or positioned within linear progress. They can contain text, HTML, images, or even Blazor components.

Common Use Cases:

• Progress percentage with custom styling
• Status text ("Uploading...", "Processing...")
• Time remaining estimates
• Icons or images
• Multi-line information (percentage + label)
• Dynamic content based on progress

ProgressBarAnnotations Setup

Annotations are added using the ProgressBarAnnotations collection, which contains one or more ProgressBarAnnotation elements:

Basic Structure:

<SfProgressBar ...>
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <!-- Your content here -->
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

ContentTemplate Usage

The ContentTemplate property defines the annotation content using standard Razor syntax, allowing you to embed custom HTML and Razor code within annotations.

Simple Text Annotation:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="60" 
               Height="160px" 
               Width="160px" 
               TrackThickness="10" 
               ProgressThickness="10">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size:20px; font-weight:bold; color:#000000;">
                    <span>60%</span>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Adding Text Annotations

Use the Value property along with annotations to dynamically display text content based on the current progress value.

Simple Percentage Display:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="60" 
               Height="160px" 
               Width="160px" 
               TrackColor="#FFD939" 
               Radius="100%" 
               InnerRadius="190%" 
               ProgressColor="white" 
               TrackThickness="80" 
               ProgressThickness="10" 
               CornerRadius="CornerType.Round">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size:20px; font-weight:bold; color:#ffffff;">
                    <span>60%</span>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Multi-Line Text:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Height="180px" 
               Width="180px" 
               ProgressColor="#28a745"
               TrackThickness="12"
               ProgressThickness="12">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 32px; font-weight: bold; color: #28a745;">
                        75%
                    </div>
                    <div style="font-size: 14px; color: #666;">
                        Complete
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Dynamic Text Based on Progress:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="@currentProgress" 
               Height="180px" 
               Width="180px" 
               ProgressColor="#0d6efd"
               TrackThickness="15"
               ProgressThickness="15">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 28px; font-weight: bold; color: #0d6efd;">
                        @currentProgress%
                    </div>
                    <div style="font-size: 12px; color: #666;">
                        @GetStatusMessage()
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

@code {
    private double currentProgress = 45;
    
    private string GetStatusMessage()
    {
        return currentProgress switch
        {
            (< 25) => "Getting started...",
            (< 50) => "In progress...",
            (< 75) => "Almost there...",
            (< 100) => "Finishing up...",
            _ => "Complete!"
        };
    }
}

Adding Custom HTML/Components

Use the ContentTemplate property to include icons, images, and custom components within annotations for enhanced visual representation.

With Icons:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="85" 
               Height="160px" 
               Width="160px" 
               ProgressColor="#ff9800"
               TrackThickness="12"
               ProgressThickness="12">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <i class="fas fa-download" style="font-size: 24px; color: #ff9800;"></i>
                    <div style="font-size: 20px; font-weight: bold; color: #ff9800; margin-top: 5px;">
                        85%
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

With Images:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="92" 
               Height="200px" 
               Width="200px" 
               ProgressColor="#4caf50"
               TrackThickness="10"
               ProgressThickness="10">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <img src="success-icon.png" alt="Success" style="width: 48px; height: 48px;" />
                    <div style="font-size: 24px; font-weight: bold; color: #4caf50; margin-top: 10px;">
                        92%
                    </div>
                    <div style="font-size: 12px; color: #666;">
                        Nearly done!
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Complex Layout:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="@uploadProgress" 
               Height="220px" 
               Width="220px" 
               ProgressColor="#6f42c1"
               TrackThickness="15"
               ProgressThickness="15">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center; padding: 10px;">
                    <div style="font-size: 36px; font-weight: bold; color: #6f42c1;">
                        @uploadProgress%
                    </div>
                    <div style="font-size: 14px; color: #666; margin-top: 5px;">
                        Uploading document.pdf
                    </div>
                    <div style="font-size: 12px; color: #999; margin-top: 5px;">
                        @GetFileSize() of 50 MB
                    </div>
                    <div style="font-size: 11px; color: #aaa; margin-top: 5px;">
                        ~@GetTimeRemaining() remaining
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

@code {
    private double uploadProgress = 67;
    
    private string GetFileSize()
    {
        return $"{uploadProgress * 0.5:F1} MB";
    }
    
    private string GetTimeRemaining()
    {
        var remainingPercent = 100 - uploadProgress;
        var seconds = remainingPercent * 0.5; // Estimate
        return $"{seconds:F0} seconds";
    }
}

Positioning Annotations

The annotations are automatically positioned by the component's layout engine. Use CSS styling within the ContentTemplate to further customize positioning.

Centered (Default): Annotations are automatically centered within the progress bar, which works perfectly for circular types:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="70" 
               Height="160px" 
               Width="160px">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size: 24px; font-weight: bold;">70%</div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

For Linear Progress Bars: Annotations appear centered within the linear bar. Use CSS for specific positioning:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="60" 
               Height="80">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style=" display: flex; justify-content: center; align-items: center; height: 100%; font-size: 18px;
                    font-weight: bold; color: white; white-space: nowrap;">
                    60% Complete
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Multiple Annotations

Add multiple ProgressBarAnnotation elements within the ProgressBarAnnotations collection for layered information:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="200px" 
               Width="200px" 
               ProgressColor="#e91e63"
               TrackThickness="15"
               ProgressThickness="15">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 40px; font-weight: bold; color: #e91e63;">
                        80
                    </div>
                    <div style="font-size: 16px; color: #666; margin-top: 5px;">
                        out of 100
                    </div>
                    <div style="font-size: 14px; color: #999; margin-top: 10px;">
                        Points
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Note: While you can add multiple ProgressBarAnnotation elements, they will overlay each other at the center. Use CSS positioning to arrange them if needed.

Styling Annotations

Customize the appearance of annotations using inline styles within the ContentTemplate property to control fonts, colors, spacing, and backgrounds.

Custom Fonts and Colors:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="55" 
               Height="180px" 
               Width="180px" 
               ProgressColor="#3f51b5"
               TrackThickness="12"
               ProgressThickness="12">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center; font-family: 'Arial', sans-serif;">
                    <div style="font-size: 48px; font-weight: 700; color: #3f51b5; line-height: 1;">
                        55
                    </div>
                    <div style="font-size: 16px; font-weight: 400; color: #757575; margin-top: 5px; letter-spacing: 1px;">
                        PERCENT
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

With Background:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="88" 
               Height="200px" 
               Width="200px" 
               ProgressColor="#00bcd4"
               TrackThickness="10"
               ProgressThickness="10">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="background: white; border-radius: 50%; padding: 20px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); text-align: center;">
                    <div style="font-size: 32px; font-weight: bold; color: #00bcd4;">
                        88%
                    </div>
                    <div style="font-size: 12px; color: #666;">
                        Success Rate
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Labels (ShowProgressValue)

Enabling Progress Labels

The ShowProgressValue property enables automatic display of the progress percentage on the progress bar component:

Linear with Label:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="50" 
               Height="60" 
               Width="90%" 
               ShowProgressValue="true" 
               TrackThickness="24" 
               ProgressThickness="24" 
               TrackColor="#F8C7D8" 
               ProgressColor="#E3165B" 
               CornerRadius="CornerType.Round">
</SfProgressBar>

Circular with Label:

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Height="160px" 
               Width="160px" 
               ShowProgressValue="true" 
               TrackThickness="12" 
               ProgressThickness="12">
</SfProgressBar>

Default Percentage Format

When the ShowProgressValue property is set to true, the progress is displayed as a percentage (e.g., "50%") by default:

<SfProgressBar Type="ProgressType.Linear" 
               Value="65" 
               ShowProgressValue="true" 
               Height="60">
</SfProgressBar>

Result: Displays "65%" within or near the progress bar.

Custom Text Formatting

Use the TextRender event in the ProgressBarEvents collection to customize the displayed text before rendering:

Custom Label Format:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="50" 
               Height="60" 
               Width="90%" 
               ShowProgressValue="true" 
               TrackColor="#F8C7D8" 
               ProgressColor="#E3165B" 
               TrackThickness="24" 
               CornerRadius="CornerType.Round" 
               ProgressThickness="24">
    <ProgressBarEvents TextRender="@TextHandler"></ProgressBarEvents>
</SfProgressBar>

@code{
    public void TextHandler(Syncfusion.Blazor.ProgressBar.TextRenderEventArgs args)
    {
        args.Text = $"Progress: {args.Text}";
    }
}

Result: Displays "Progress: 50%" instead of "50%".

TextRender Event

The TextRender event in ProgressBarEvents fires before the text is rendered, allowing full customization of text through TextRenderEventArgs:

Event Arguments:

• args.Value - Current progress value
• args.Text - Current text (can be modified)

Examples:

Fraction Format:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="40" 
               ShowProgressValue="true" 
               Maximum="100"
               Height="60">
    <ProgressBarEvents TextRender="@FractionFormat"></ProgressBarEvents>
</SfProgressBar>

@code{
    public void FractionFormat(Syncfusion.Blazor.ProgressBar.TextRenderEventArgs args)
    {
        args.Text = $"{args.Text}/100";
    }
}

Result: "40/100"

Custom Units:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@filesProcessed" 
               Maximum="@totalFiles"
               ShowProgressValue="true" 
               Height="60">
    <ProgressBarEvents TextRender="@FilesFormat"></ProgressBarEvents>
</SfProgressBar>

@code{
    private double filesProcessed = 37;
    private double totalFiles = 100;
    
    public void FilesFormat(Syncfusion.Blazor.ProgressBar.TextRenderEventArgs args)
    {
        args.Text = $"{filesProcessed} of {totalFiles} files";
    }
}

Result: "37 of 100 files"

Conditional Formatting:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="@progress" 
               ShowProgressValue="true" 
               Height="60">
    <ProgressBarEvents TextRender="@ConditionalFormat"></ProgressBarEvents>
</SfProgressBar>

@code{
    private double progress = 100;
    
    public void ConditionalFormat(Syncfusion.Blazor.ProgressBar.TextRenderEventArgs args)
    {
        // Remove % if it exists and trim spaces
        string raw = args.Text.Replace("%", "").Trim();
        int.TryParse(raw, out int value)
        if (value >= 100)
        {
            args.Text = "✓ Complete!";
        }
        else if (value >= 75)
        {
            args.Text = $"{value}% - Almost done";
        }
        else
        {
            args.Text = $"{value}%";
        }
    }
}

Label Positioning

Labels are automatically positioned by the component's layout engine:

• Linear: Inside or outside the progress bar depending on space
• Circular: Centered within the circle

The positioning is controlled internally and cannot be manually repositioned. For custom positioning, use annotations with the ContentTemplate property instead.

Combining Annotations and Labels

You can use both the ShowProgressValue property and annotations simultaneously with ProgressBarAnnotations, though typically you choose one:

Both Enabled (overlapping):

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="70" 
               Height="160px" 
               Width="160px" 
               ShowProgressValue="true">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size: 24px; font-weight: bold; color: #ff0000;">
                    Custom: 70%
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

⚠️ Warning: This may cause overlapping text. Generally, choose either labels OR annotations, not both.

Recommended Pattern:

@using Syncfusion.Blazor.ProgressBar

<!-- Use ShowProgressValue for simple percentage display -->
<SfProgressBar Value="60" ShowProgressValue="true" Height="60">
</SfProgressBar>

<!-- Use Annotations for custom, styled, or complex content -->
<SfProgressBar Type="ProgressType.Circular" Value="60" Height="160px" Width="160px">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 28px; font-weight: bold;">60%</div>
                    <div style="font-size: 12px; color: #666;">Complete</div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Complete Examples

Example 1: Goal Tracker

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="@goalProgress" 
               Height="200px" 
               Width="200px" 
               ProgressColor="#ff6b6b"
               TrackColor="#ffe0e0"
               TrackThickness="15"
               ProgressThickness="15">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 14px; color: #999; text-transform: uppercase; letter-spacing: 1px;">
                        Goal
                    </div>
                    <div style="font-size: 42px; font-weight: bold; color: #ff6b6b; margin: 5px 0;">
                        @goalProgress%
                    </div>
                    <div style="font-size: 16px; color: #666;">
                        $@((goalProgress * 1000).ToString("N0"))
                    </div>
                    <div style="font-size: 12px; color: #999;">
                        of $100,000
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

@code {
    private double goalProgress = 82;
}

Example 2: File Upload with Time

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@uploadProgress" 
               Height="70"
               TrackThickness="24"
               ProgressThickness="24"
               ProgressColor="#28a745"
               TrackColor="#e9ecef"
               CornerRadius="CornerType.Round">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="display: flex; justify-content: center; align-items: center; height: 100%; font-size: 18px;
                    font-weight: bold; color: white; white-space: nowrap;">
                    <div style="font-size: 16px;">@uploadProgress%</div>
                    <div style="font-size: 11px; opacity: 0.9;">~@GetTimeRemaining() remaining</div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

@code {
    private double uploadProgress = 45;
    
    private string GetTimeRemaining()
    {
        var remainingSeconds = (100 - uploadProgress) * 0.8;
        return $"{remainingSeconds:F0}s";
    }
}

Example 3: Battery Level Indicator

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="@batteryLevel" 
               Height="140px" 
               Width="140px" 
               ProgressColor="@GetBatteryColor()"
               TrackColor="#f0f0f0"
               TrackThickness="10"
               ProgressThickness="10">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <i class="fas fa-battery-@GetBatteryIcon()" style="font-size: 32px; color: @GetBatteryColor();"></i>
                    <div style="font-size: 20px; font-weight: bold; color: @GetBatteryColor(); margin-top: 5px;">
                        @batteryLevel%
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

@code {
    private double batteryLevel = 35;
    
    private string GetBatteryColor()
    {
        return batteryLevel switch
        {
            > 60 => "#28a745",
            > 20 => "#ffc107",
            _ => "#dc3545"
        };
    }
    
    private string GetBatteryIcon()
    {
        return batteryLevel switch
        {
            > 75 => "full",
            > 50 => "three-quarters",
            > 25 => "half",
            > 10 => "quarter",
            _ => "empty"
        };
    }
}

Best Practices

1. Choose Between Annotations and Labels:

• Use ShowProgressValue for simple percentage display
• Use annotations for custom styling, multi-line content, or complex layouts

2. Keep Annotations Readable:

• Ensure sufficient contrast between text and background
• Use appropriate font sizes (minimum 14px for body text)
• Test readability at different screen sizes

3. Circular Progress Annotations:

• Center content vertically and horizontally
• Account for available space (inner radius)
• Use relative font sizes for responsiveness

4. Linear Progress Annotations:

• Ensure text doesn't overflow the progress bar height
• Use contrasting colors (white text on dark progress)
• Consider positioning for different progress values

5. Dynamic Content:

• Update annotations when progress changes
• Use StateHasChanged() to refresh annotations
• Avoid heavy computations in ContentTemplate

6. Accessibility:

• Annotations are visual only - ensure screen readers can access progress
• Don't rely solely on annotations for critical information
• Provide text alternatives for icon-only annotations

7. Performance:

• Minimize complex HTML in annotations
• Avoid frequent annotation updates (throttle if needed)
• Use simple CSS for styling rather than nested components

8. Styling Consistency:

• Match annotation styling to your design system
• Coordinate annotation colors with progress bar colors
• Maintain consistent typography across annotations

ProgressBar API Reference

Table of Contents

• Overview
• Core Component
• SfProgressBar
• Child Components
• ProgressBarAnimation
• ProgressBarEvents
• ProgressBarAnnotations
• ProgressBarAnnotation
• ProgressBarLabelStyle
• ProgressBarMargin
• ProgressBarRangeColor
• ProgressBarRangeColors
• Enums
• ProgressType
• CornerType
• ModeType
• TextAlignmentType
• Notes

Overview

This reference summarizes the official Syncfusion.Blazor.ProgressBar API surface for SfProgressBar and its related child components, events, and enums.

Core Component

SfProgressBar

Main rendering component for the ProgressBar control.

Properties

Methods

Child Components

ProgressBarAnimation

Controls progress animation behavior.

ProgressBarEvents

Defines event callbacks for the ProgressBar.

ProgressBarAnnotations

Container for one or more ProgressBarAnnotation items.

ProgressBarAnnotation

Defines an annotation overlay for the progress bar.

ProgressBarLabelStyle

Controls label styling.

ProgressBarMargin

Controls outer spacing.

ProgressBarRangeColor

Defines a single range color.

ProgressBarRangeColors

Container for multiple ProgressBarRangeColor items.

Enums

ProgressType

CornerType

ModeType

TextAlignmentType

Notes

• IsStriped applies to linear progress bars.
• Radius, InnerRadius, StartAngle, and EndAngle apply to circular progress bars.
• RefreshAsync() is the public method available on SfProgressBar for re-rendering.

ProgressBar Customization

Table of Contents

• Overview
• Segments
• SegmentCount Property
• EnableProgressSegments
• SegmentColor (Multi-Color)
• Use Cases for Segments
• Thickness Customization
• TrackThickness
• ProgressThickness
• SecondaryProgressThickness
• Examples for Both Types
• Radius and Shape
• Radius Property (Circular)
• InnerRadius Property
• CornerRadius Property
• Creating Donut Charts
• Colors
• ProgressColor
• TrackColor
• SecondaryProgressColor
• Range Colors with Gradients
• Color Selection Guide
• Margin and Spacing
• ProgressBarMargin Configuration
• Layout Considerations
• RTL Support
• EnableRtl Property
• Localization Considerations
• Visibility Control
• Visible Property
• Dynamic Show/Hide
• Complete Visibility Example
• Complete Customization Examples

Overview

The Blazor ProgressBar component offers extensive customization options to match your application's design system and requirements. This guide covers all visual and behavioral customization capabilities.

Customization Categories:

• Segments: Divide progress into discrete blocks
• Thickness: Control width of track and progress indicators
• Radius: Adjust circular progress dimensions and corner rounding
• Colors: Customize progress, track, and secondary progress colors
• Margin: Control spacing around the component
• RTL: Right-to-left language support
• Visibility: Dynamic show/hide control

Segments

Segments divide the progress bar into distinct visual blocks, useful for representing discrete steps or stages. The SegmentCount, EnableProgressSegments, and SegmentColor properties will be used for segment configuration.

SegmentCount Property

The SegmentCount property divides progress into equal segments:

Linear Segments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60" 
               SegmentCount="8" 
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Result: Progress bar divided into 8 equal blocks.

Circular Segments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="100" 
               Height="180" 
               SegmentCount="8" 
               TrackColor="#696969"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Result: Circular progress divided into 8 arc segments.

Segment Behavior:

• Progress fills segments sequentially
• Each segment represents an equal portion of the range
• Partially filled segments show fractional progress

EnableProgressSegments

The EnableProgressSegments property creates segments without track background, showing only filled segments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               EnableProgressSegments="true" 
               Value="100" 
               Height="180" 
               SegmentCount="8" 
               TrackColor="#696969"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Difference:

• SegmentCount only: Shows track with segment dividers, progress fills segments
• EnableProgressSegments="true": Shows only filled segments, no track background

Comparison:

<!-- With track background -->
<SfProgressBar SegmentCount="6" Value="50" Height="60">
</SfProgressBar>

<!-- Without track background (segments only) -->
<SfProgressBar EnableProgressSegments="true" SegmentCount="6" Value="50" Height="60">
</SfProgressBar>

SegmentColor (Multi-Color)

Apply different colors to segments using the SegmentColor array:

Multi-Color Circular Segments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="100" 
               Height="180" 
               SegmentCount="8" 
               SegmentColor='new string[] { "#00bdaf", "#2f7ecc", "#e9648e", "#fbb78a" }' 
               TrackColor="#696969"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Color Array Behavior:

• Colors are applied in sequence to segments
• If fewer colors than segments, colors repeat cyclically
• 4 colors for 8 segments: Colors repeat twice

Multi-Color with EnableProgressSegments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               EnableProgressSegments="true" 
               Value="100" 
               Height="180" 
               SegmentCount="8" 
               SegmentColor='new string[] { "#00bdaf", "#2f7ecc", "#e9648e", "#fbb78a" }' 
               TrackColor="#696969"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Linear Multi-Color Segments:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60" 
               SegmentCount="4" 
               SegmentColor='new string[] { "#28a745", "#17a2b8", "#ffc107", "#dc3545" }' 
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Use Cases for Segments

Multi-Step Form (5 steps):

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@((currentStep / 5.0) * 100)" 
               Height="60" 
               SegmentCount="5"
               TrackThickness="16"
               ProgressThickness="16"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

@code {
    private int currentStep = 3; // On step 3 of 5
}

Skill Level Indicator:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="62.5" 
               Height="160px"
               Width="160px"
               SegmentCount="8" 
               SegmentColor='new string[] { "#4caf50", "#8bc34a", "#cddc39", "#ffeb3b", "#ffc107", "#ff9800", "#ff5722", "#f44336" }' 
               TrackThickness="12"
               ProgressThickness="12">
</SfProgressBar>
<!-- 5 out of 8 levels achieved -->

Color-Coded Priority Levels:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60" 
               SegmentCount="3" 
               SegmentColor='new string[] { "#28a745", "#ffc107", "#dc3545" }'>
</SfProgressBar>
<!-- Green (low), Yellow (medium), Red (high) priority -->

Thickness Customization

Control the visual weight of track, progress, and secondary progress indicators. The TrackThickness, ProgressThickness, and SecondaryProgressThickness properties will be used for thickness configuration.

TrackThickness

The TrackThickness property sets the background track width:

Linear Track Thickness:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60" 
               Width="90%" 
               TrackThickness="24" 
               ProgressThickness="24" 
               ShowProgressValue="true" 
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Circular Track Thickness:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="160px"
               Width="160px"
               TrackThickness="20" 
               ProgressThickness="20">
</SfProgressBar>

Recommendations:

• Linear: 8-30px (16-24px ideal)
• Circular: 6-20px (10-15px ideal)
• Match TrackThickness and ProgressThickness for uniform appearance
• Thicker tracks for emphasis, thinner for subtlety

ProgressThickness

The ProgressThickness property sets the progress indicator width:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               TrackThickness="20" 
               ProgressThickness="20" 
               Height="60">
</SfProgressBar>

Different Thickness Example:

@using Syncfusion.Blazor.ProgressBar

<!-- Thinner progress on thicker track -->
<SfProgressBar Type="ProgressType.Linear" 
               Value="50" 
               TrackThickness="24" 
               ProgressThickness="12" 
               Height="60">
</SfProgressBar>

Use Cases:

• Same thickness: Uniform, clean appearance
• Thinner progress: Subtle, minimal design
• Thicker progress: Emphasis, bold design

SecondaryProgressThickness

For buffer states, control secondary progress thickness separately:

Linear Secondary Progress:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="80" 
               SecondaryProgress="50" 
               SecondaryProgressThickness="30" 
               TrackThickness="20"
               ProgressThickness="20"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Circular Secondary Progress:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               SecondaryProgress="40" 
               SecondaryProgressThickness="20" 
               TrackThickness="12"
               ProgressThickness="12"
               Height="160px"
               Width="160px"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Layering:

• Secondary progress appears behind primary progress
• Can be thicker or thinner than primary
• Use different thickness for visual hierarchy

Examples for Both Types

Thin Minimal Style:

<!-- Linear -->
<SfProgressBar Type="ProgressType.Linear" 
               Value="65" 
               Height="40"
               TrackThickness="4" 
               ProgressThickness="4">
</SfProgressBar>

<!-- Circular -->
<SfProgressBar Type="ProgressType.Circular" 
               Value="65" 
               Height="120px"
               Width="120px"
               TrackThickness="4" 
               ProgressThickness="4">
</SfProgressBar>

Bold Prominent Style:

<!-- Linear -->
<SfProgressBar Type="ProgressType.Linear" 
               Value="65" 
               Height="80"
               TrackThickness="30" 
               ProgressThickness="30">
</SfProgressBar>

<!-- Circular -->
<SfProgressBar Type="ProgressType.Circular" 
               Value="65" 
               Height="200px"
               Width="200px"
               TrackThickness="18" 
               ProgressThickness="18">
</SfProgressBar>

Radius and Shape

Control circular progress dimensions and corner rounding. The Radius, InnerRadius, and CornerRadius properties will be used for radius and shape configuration.

Radius Property (Circular)

The Radius property adjusts the outer radius as a percentage:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="60" 
               Height="160px" 
               Width="160px" 
               Radius="100%" 
               TrackThickness="10" 
               ProgressThickness="10"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Radius Values:

• "100%" - Full radius (default, touches container edges)
• "80%" - 80% of container, leaves margin
• "90%" - Slight inset from edges

Use Cases:

• Adjust to prevent clipping
• Create visual spacing
• Align with other circular elements

InnerRadius Property

The InnerRadius property creates the donut hole:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="60" 
               Height="160px" 
               Width="160px" 
               Radius="100%" 
               InnerRadius="80%" 
               TrackColor="#FFD939" 
               ProgressColor="white" 
               TrackThickness="80" 
               ProgressThickness="10" 
               CornerRadius="CornerType.Round" 
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

InnerRadius Values:

• "90%" - Thin ring (small donut hole)
• "70%" - Medium ring
• "50%" - Thick ring (large donut hole)
• "190%" - Can exceed 100% for special effects

Relationship with TrackThickness:

• Large InnerRadius + thick TrackThickness = thin ring appearance
• Small InnerRadius + thin TrackThickness = standard donut

CornerRadius Property

The CornerRadius property rounds the edges of progress indicators:

Round Corners:

<SfProgressBar Type="ProgressType.Linear" 
               Value="60" 
               Height="60"
               TrackThickness="24" 
               ProgressThickness="24" 
               CornerRadius="CornerType.Round">
</SfProgressBar>

Square Corners:

<SfProgressBar Type="ProgressType.Linear" 
               Value="60" 
               Height="60"
               TrackThickness="24" 
               ProgressThickness="24" 
               CornerRadius="CornerType.Square">
</SfProgressBar>

Options:

• CornerType.Round - Rounded/pill-shaped ends
• CornerType.Square - Sharp 90-degree corners (default)

Works with Both Types:

• Linear: Rounds the left and right ends
• Circular: Rounds the start and end of the arc

Creating Donut Charts

Combine properties for custom donut appearances:

Wide Donut:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Height="180px" 
               Width="180px" 
               Radius="100%" 
               InnerRadius="60%" 
               TrackThickness="15" 
               ProgressThickness="15" 
               TrackColor="#e0e0e0"
               ProgressColor="#2196f3">
</SfProgressBar>

Thin Ring:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Height="180px" 
               Width="180px" 
               Radius="100%" 
               InnerRadius="92%" 
               TrackThickness="8" 
               ProgressThickness="8" 
               TrackColor="#e0e0e0"
               ProgressColor="#2196f3">
</SfProgressBar>

Thick Track with Thin Progress:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="60" 
               Height="160px" 
               Width="160px" 
               Radius="80%" 
               InnerRadius="190%" 
               TrackColor="#FFD939" 
               ProgressColor="white" 
               TrackThickness="80" 
               ProgressThickness="10" 
               CornerRadius="CornerType.Round">
</SfProgressBar>

Colors

Customize progress, track, and secondary progress colors to match your design system. The ProgressColor, TrackColor, and SecondaryProgressColor properties will be used for color customization.

ProgressColor

The ProgressColor property sets the main progress indicator color:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               ProgressColor="#28a745" 
               Height="60">
</SfProgressBar>

Accepts:

• Hex colors: "#28a745"
• RGB: "rgb(40, 167, 69)"
• Named colors: "green" (use with caution)

TrackColor

The TrackColor property sets the background track color:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="50" 
               ProgressColor="#E3165B" 
               TrackColor="#F8C7D8" 
               Height="60">
</SfProgressBar>

Best Practices:

• Use lighter shade of ProgressColor for subtle contrast
• Use neutral gray (#e0e0e0, #f0f0f0) for universal themes
• Ensure sufficient contrast with page background

SecondaryProgressColor

The SecondaryProgressColor property colors the secondary progress:

Linear with Secondary Color:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               ProgressColor="#cc0202" 
               Value="50" 
               SecondaryProgress="60" 
               SecondaryProgressColor="#faa7a7" 
               TrackThickness="10"
               ProgressThickness="10"
               SecondaryProgressThickness="10"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Circular with Secondary Color:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               ProgressColor="#cc0202" 
               Value="50" 
               SecondaryProgress="60" 
               SecondaryProgressColor="#faa7a7" 
               TrackThickness="10"
               ProgressThickness="10"
               SecondaryProgressThickness="10"
               Height="160px"
               Width="160px"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Color Relationships:

• Secondary typically lighter than primary
• Both should contrast with track
• Consider colorblind-friendly palettes

Range Colors with Gradients

Apply different colors to specific progress ranges with optional gradients:

Basic Range Colors:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="100" IsGradient="false">
    <ProgressBarRangeColors>
        <ProgressBarRangeColor Start="0" End="25" Color="#00bdaf"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="25" End="50" Color="#2f7ecc"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="50" End="75" Color="#e9648e"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="75" End="100" Color="#fbb78a"></ProgressBarRangeColor>
    </ProgressBarRangeColors>
</SfProgressBar>

With Gradient Effect:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Value="100" IsGradient="true">
    <ProgressBarRangeColors>
        <ProgressBarRangeColor Start="0" End="25" Color="#00bdaf"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="25" End="50" Color="#2f7ecc"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="50" End="75" Color="#e9648e"></ProgressBarRangeColor>
        <ProgressBarRangeColor Start="75" End="100" Color="#fbb78a"></ProgressBarRangeColor>
    </ProgressBarRangeColors>
</SfProgressBar>

Properties:

• Start - Range start value
• End - Range end value
• Color - Color for this range
• IsGradient - Smooth transitions between colors (true) vs hard stops (false)

Use Cases:

• Temperature: Blue (cold) → Yellow (warm) → Red (hot)
• Performance: Green (good) → Yellow (fair) → Red (poor)
• Progress Stages: Different color per milestone
• Risk Levels: Low (green) → Medium (yellow) → High (orange) → Critical (red)

Color Selection Guide

Semantic Colors (Bootstrap-inspired):

@using Syncfusion.Blazor.ProgressBar

<!-- Success/Complete -->
<SfProgressBar ProgressColor="#28a745" TrackColor="#d4edda" Value="100" Height="60">
</SfProgressBar>

<!-- Info/Processing -->
<SfProgressBar ProgressColor="#17a2b8" TrackColor="#d1ecf1" Value="60" Height="60">
</SfProgressBar>

<!-- Warning -->
<SfProgressBar ProgressColor="#ffc107" TrackColor="#fff3cd" Value="75" Height="60">
</SfProgressBar>

<!-- Danger/Error -->
<SfProgressBar ProgressColor="#dc3545" TrackColor="#f8d7da" Value="90" Height="60">
</SfProgressBar>

<!-- Primary -->
<SfProgressBar ProgressColor="#007bff" TrackColor="#cfe2ff" Value="50" Height="60">
</SfProgressBar>

Contrast Guidelines:

• Ensure 3:1 contrast ratio minimum between progress and track
• Ensure 4.5:1 contrast ratio between progress and background for accessibility
• Test with colorblind simulators
• Provide non-color indicators (percentage text) for critical information

Margin and Spacing

Control spacing around the progress bar. The ProgressBarMargin component will be used for margin and spacing configuration.

ProgressBarMargin Configuration

Control spacing around the progress bar using the ProgressBarMargin component:

Default Margins (10px all sides):

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="150px" 
               Width="150px" 
               TrackThickness="20" 
               ProgressThickness="20">
    <!-- Default: Left="10" Right="10" Top="10" Bottom="10" -->
</SfProgressBar>

Zero Margins:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Height="150px" 
               Width="150px" 
               Value="80" 
               TrackThickness="20" 
               ProgressThickness="20">
    <ProgressBarMargin Left="0" Right="0" Bottom="0" Top="0">
    </ProgressBarMargin>
</SfProgressBar>

Custom Margins:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               Height="60">
    <ProgressBarMargin Left="20" Right="20" Bottom="5" Top="5">
    </ProgressBarMargin>
</SfProgressBar>

Layout Considerations

Tight Layouts (zero/minimal margins):

• Use when progress bar is in a bordered container
• Cards, dialogs, or confined spaces
• Maximizes available space

Spaced Layouts (standard/large margins):

• Use in open layouts for breathing room
• Prevents visual crowding
• Improves touch target size

Asymmetric Margins:

<!-- More space at bottom for labels -->
<SfProgressBar Value="80" Height="60">
    <ProgressBarMargin Top="5" Bottom="20" Left="10" Right="10">
    </ProgressBarMargin>
</SfProgressBar>
<p style="margin-top: -15px;">Loading complete</p>

RTL Support

The EnableRtl property will be used for right-to-left language support.

EnableRtl Property

Enable right-to-left rendering for RTL languages (Arabic, Hebrew, etc.):

Linear RTL:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar EnableRtl="true" 
               Value="50" 
               Type="ProgressType.Linear"
               Height="60">
</SfProgressBar>

Effect: Progress fills from right to left instead of left to right.

Circular RTL:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar EnableRtl="true" 
               Value="80" 
               Type="ProgressType.Circular"
               Height="160px"
               Width="160px">
</SfProgressBar>

Effect: Progress arc travels counterclockwise instead of clockwise.

Localization Considerations

Conditional RTL Based on Culture:

@using Syncfusion.Blazor.ProgressBar
@using System.Globalization

<SfProgressBar EnableRtl="@isRtl" 
               Value="70" 
               Type="ProgressType.Linear"
               Height="60"
               ShowProgressValue="true">
</SfProgressBar>

@code {
    private bool isRtl = CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft;
}

Full RTL Example:

@using Syncfusion.Blazor.ProgressBar

<div dir="rtl" style="padding: 20px;">
    <h4>تحميل الملف</h4>
    
    <SfProgressBar EnableRtl="true" 
                   Value="60" 
                   Type="ProgressType.Linear"
                   Height="60"
                   ShowProgressValue="true"
                   TrackThickness="16"
                   ProgressThickness="16">
    </SfProgressBar>
    
    <p>٪60 مكتمل</p>
</div>

Visibility Control

The Visible property will be used for visibility control.

Visible Property

Control whether the progress bar is rendered:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60" 
               Visible="@isVisible"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

@code {
    private bool isVisible = true;
}

Use Cases:

• Show progress bar only during operations
• Hide when operation completes
• Conditional display based on state

Dynamic Show/Hide

Toggle visibility based on operation state:

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@progressValue" 
               Height="60" 
               Visible="@showProgressBar"
               ShowProgressValue="true">
</SfProgressBar>

<button class="btn btn-primary" @onclick="StartOperation">Start</button>

@code {
    private double progressValue = 0;
    private bool showProgressBar = false;
    private System.Threading.Timer? timer;

    private void StartOperation()
    {
        progressValue = 0;
        showProgressBar = true;

        timer?.Dispose();
        timer = new System.Threading.Timer(_ =>
        {
            if (progressValue >= 100)
            {
                showProgressBar = false;
                timer?.Dispose();
            }
            else
            {
                progressValue += 10;
            }

            InvokeAsync(StateHasChanged); 

        }, null, 0, 500);
    }

    public void Dispose()
    {
        timer?.Dispose();
    }
}

Complete Visibility Example

Show progress during upload, hide with success message:

@using Syncfusion.Blazor.ProgressBar

<div style="padding: 20px;">
    <SfProgressBar Type="ProgressType.Linear" 
                   Value="@uploadProgress" 
                   Height="60" 
                   Visible="@showProgressBar"
                   TrackThickness="16"
                   ProgressThickness="16"
                   ProgressColor="#28a745"
                   TrackColor="#e0e0e0"
                   Minimum="0" 
                   Maximum="100">
        <ProgressBarAnimation Enable="true" Duration="300"></ProgressBarAnimation>
        <ProgressBarEvents AnimationComplete="@OnUploadComplete"></ProgressBarEvents>
    </SfProgressBar>
    
    <div style="text-align: center; margin-top: 10px;">
        <p style="color: @messageColor; font-size: larger; font-weight: bold;">
            @statusMessage
        </p>
    </div>
    
    <button class="btn btn-primary" @onclick="StartUpload" disabled="@isUploading">
        Upload File
    </button>
</div>

@code {
    private double uploadProgress = 0;
    private bool showProgressBar = false;
    private bool isUploading = false;
    private string statusMessage = "";
    private string messageColor = "#000";
    private System.Threading.Timer? timer;
    
    private void StartUpload()
    {
        isUploading = true;
        showProgressBar = true;
        uploadProgress = 0;
        statusMessage = "";
        
        timer = new System.Threading.Timer(_ =>
        {
            if (uploadProgress < 100)
            {
                uploadProgress += 10;
                InvokeAsync(StateHasChanged);
            }
            else
            {
                timer?.Dispose();
            }
        }, null, 0, 300);
    }
    
    private void OnUploadComplete(ProgressValueEventArgs args)
    {
        if (args.Value == 100)
        {
            showProgressBar = false;
            statusMessage = "UPLOAD SUCCESS!";
            messageColor = "#28a745";
            isUploading = false;
            StateHasChanged();
            
            // Clear message after 3 seconds
            Task.Delay(3000).ContinueWith(_ =>
            {
                InvokeAsync(() =>
                {
                    statusMessage = "";
                    StateHasChanged();
                });
            });
        }
    }
    
    public void Dispose()
    {
        timer?.Dispose();
    }
}

Complete Customization Examples

Example 1: Fully Customized Linear Progress

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="75" 
               Height="70"
               ShowProgressValue="true"
               TrackThickness="26"
               ProgressThickness="26"
               CornerRadius="CornerType.Round"
               ProgressColor="#6f42c1"
               TrackColor="#e9ecef"
               IsGradient="false"
               Minimum="0" 
               Maximum="100">
    <ProgressBarMargin Left="15" Right="15" Top="10" Bottom="10">
    </ProgressBarMargin>
    <ProgressBarAnimation Enable="true" Duration="500" Delay="0">
    </ProgressBarAnimation>
</SfProgressBar>

Example 2: Fully Customized Circular Progress

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="82" 
               Height="200px"
               Width="200px"
               Radius="95%"
               InnerRadius="75%"
               TrackThickness="15"
               ProgressThickness="15"
               CornerRadius="CornerType.Round"
               ProgressColor="#ff6b6b"
               TrackColor="#f0f0f0"
               Minimum="0" 
               Maximum="100">
    <ProgressBarMargin Left="10" Right="10" Top="10" Bottom="10">
    </ProgressBarMargin>
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="text-align: center;">
                    <div style="font-size: 14px; font-weight: bold; color: #ff6b6b;">
                        82%
                    </div>
                    <div style="font-size: 14px; color: #ff6b6b;">
                        Complete
                    </div>
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Example 3: Multi-Color Segmented Progress

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60"
               SegmentCount="5"
               SegmentColor='new string[] { "#4caf50", "#8bc34a", "#cddc39", "#ffc107", "#ff9800" }'
               TrackThickness="20"
               ProgressThickness="20"
               TrackColor="#e0e0e0"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

Example 4: Buffer State with Custom Colors

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="45" 
               SecondaryProgress="75"
               Height="60"
               ProgressColor="#1976d2"
               SecondaryProgressColor="#90caf9"
               TrackColor="#263238"
               TrackThickness="14"
               ProgressThickness="14"
               SecondaryProgressThickness="14"
               CornerRadius="CornerType.Round"
               Minimum="0" 
               Maximum="100">
</SfProgressBar>

All customization options can be combined to create progress bars that perfectly match your application's design requirements and user experience goals.

Getting Started with Blazor ProgressBar

Table of Contents

• Overview
• Prerequisites and System Requirements
• Installation Methods
• Visual Studio Setup
• Visual Studio Code Setup
• .NET CLI Setup
• Package Installation
• Configure the Application
• Import Namespaces
• Register Syncfusion Service
• Add Stylesheet and Script Resources
• Basic Implementation
• Linear ProgressBar
• Circular ProgressBar
• Verification
• Troubleshooting Installation

Overview

This guide walks through setting up the Syncfusion Blazor ProgressBar component in a Blazor WebAssembly application. The ProgressBar component provides visual feedback for operations with determinate or indeterminate progress states.

The setup process involves: 1. Creating a Blazor WebAssembly application 2. Installing required NuGet packages 3. Configuring namespaces and services 4. Adding theme and script references 5. Implementing your first ProgressBar

Prerequisites and System Requirements

Before starting, ensure you have:

• Visual Studio 2022 (17.0 or later) OR Visual Studio Code (latest version)
• .NET SDK 6.0 or later - Verify installation:

  dotnet --version

• Internet connection for downloading NuGet packages
• Basic knowledge of Blazor and Razor syntax

System Requirements:

• Windows 10/11, macOS 10.15+, or Linux
• Minimum 4GB RAM (8GB recommended)
• 2GB free disk space

Installation Methods

Choose one of three methods to create your Blazor WebAssembly application:

Visual Studio Setup

Step 1: Create New Project 1. Open Visual Studio 2022 2. Click Create a new project 3. Search for "Blazor WebAssembly App" 4. Select Blazor WebAssembly App template 5. Click Next

Step 2: Configure Project 1. Enter Project name (e.g., ProgressBarDemo) 2. Choose Location for the project 3. Click Next

Step 3: Additional Information 1. Select Framework: .NET 6.0 or later 2. Authentication type: None (or as needed) 3. Click Create

Visual Studio will create the project structure and restore dependencies.

Visual Studio Code Setup

Step 1: Create Project via Terminal 1. Open Visual Studio Code 2. Press <kbd>Ctrl</kbd>+<kbd></kbd> (Windows/Linux) or <kbd>⌘</kbd>+<kbd></kbd> (macOS) to open integrated terminal 3. Navigate to your desired project location 4. Run:

   dotnet new blazorwasm -o ProgressBarDemo
   cd ProgressBarDemo

Step 2: Open Project 1. In VS Code, select File → Open Folder 2. Navigate to and select the ProgressBarDemo folder 3. Click Select Folder

VS Code will detect the project and may prompt to add required assets - click Yes.

.NET CLI Setup

Step 1: Verify .NET Installation

dotnet --version

Ensure version is 6.0 or higher.

Step 2: Create Blazor WebAssembly App

dotnet new blazorwasm -o ProgressBarDemo
cd ProgressBarDemo

Step 3: Verify Project Creation

dotnet build

Should complete successfully with no errors.

Package Installation

Install two required NuGet packages: 1. Syncfusion.Blazor.ProgressBar - ProgressBar component 2. Syncfusion.Blazor.Themes - Styling themes

Using Visual Studio

1. Open Tools → NuGet Package Manager → Manage NuGet Packages for Solution 2. Click Browse tab 3. Search for Syncfusion.Blazor.ProgressBar 4. Select the package and click Install 5. Repeat for Syncfusion.Blazor.Themes 6. Accept license agreements if prompted

Alternative: Package Manager Console

Install-Package Syncfusion.Blazor.ProgressBar -Version 25.1.35
Install-Package Syncfusion.Blazor.Themes -Version 25.1.35

Using Visual Studio Code or .NET CLI

Open terminal in project directory and run:

dotnet add package Syncfusion.Blazor.ProgressBar
dotnet add package Syncfusion.Blazor.Themes
dotnet restore

Verify Installation: Check the .csproj file - it should contain:

<ItemGroup>
  <PackageReference Include="Syncfusion.Blazor.ProgressBar" Version="25.1.35" />
  <PackageReference Include="Syncfusion.Blazor.Themes" Version="25.1.35" />
</ItemGroup>

Configure the Application

Import Namespaces

Open _Imports.razor file (located in project root) and add:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.ProgressBar

This makes Syncfusion components available throughout your application without repeated using statements.

Complete _Imports.razor example:

@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using ProgressBarDemo
@using ProgressBarDemo.Shared
@using Syncfusion.Blazor
@using Syncfusion.Blazor.ProgressBar

Register Syncfusion Service

Open Program.cs and register the Syncfusion Blazor service:

For .NET 6.0+:

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;
using ProgressBarDemo;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient 
{ 
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) 
});

// Register Syncfusion Blazor service
builder.Services.AddSyncfusionBlazor();

await builder.Build().RunAsync();

The AddSyncfusionBlazor() method registers all required Syncfusion services.

Add Stylesheet and Script Resources

Open wwwroot/index.html and add theme stylesheet and script references inside the <head> section:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <title>ProgressBarDemo</title>
    <base href="/" />
    <link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
    <link href="css/app.css" rel="stylesheet" />
    <link href="ProgressBarDemo.styles.css" rel="stylesheet" />
    
    <!-- Syncfusion Blazor Theme -->
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    
    <!-- Syncfusion Blazor Scripts -->
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>
<body>
    <div id="app">Loading...</div>
    <script src="_framework/blazor.webassembly.js"></script>
</body>
</html>

Available Themes:

• bootstrap5.css - Bootstrap 5 theme (default)
• material.css - Material Design theme
• fabric.css - Fluent/Fabric theme
• tailwind.css - Tailwind CSS theme
• fluent.css - Fluent 2 theme
• bootstrap4.css - Bootstrap 4 theme
• material3.css - Material 3 theme

Change the theme by replacing bootstrap5.css with your preferred theme name.

Using CDN (Alternative):

<!-- CDN References -->
<link href="https://cdn.syncfusion.com/blazor/25.1.35/styles/bootstrap5.css" rel="stylesheet" />
<script src="https://cdn.syncfusion.com/blazor/25.1.35/syncfusion-blazor.min.js" type="text/javascript"></script>

Basic Implementation

Linear ProgressBar

Create a simple linear progress bar in any Razor page (e.g., Pages/Index.razor):

@page "/"
@using Syncfusion.Blazor.ProgressBar

<h3>Linear ProgressBar Example</h3>

<SfProgressBar Type="ProgressType.Linear" 
               Value="50" 
               Minimum="0" 
               Maximum="100"
               Height="60"
               TrackThickness="12" 
               ProgressThickness="12">
</SfProgressBar>

Explanation:

• Type="ProgressType.Linear" - Creates horizontal progress bar
• Value="50" - Current progress (50%)
• Minimum="0" and Maximum="100" - Range from 0 to 100
• Height="60" - Bar height in pixels
• TrackThickness="12" - Background track thickness
• ProgressThickness="12" - Progress indicator thickness

Circular ProgressBar

Add a circular progress indicator:

@page "/circular"
@using Syncfusion.Blazor.ProgressBar

<h3>Circular ProgressBar Example</h3>

<SfProgressBar Type="ProgressType.Circular" 
               Value="70" 
               Minimum="0" 
               Maximum="100"
               Height="160px"
               Width="160px"
               TrackThickness="8" 
               ProgressThickness="8">
</SfProgressBar>

Explanation:

• Type="ProgressType.Circular" - Creates circular/donut progress bar
• Value="70" - 70% completion
• Height="160px" and Width="160px" - Circle dimensions (include 'px' suffix)
• TrackThickness="8" - Circular track thickness
• ProgressThickness="8" - Progress arc thickness

Complete Working Example

Here's a complete Index.razor with both types:

@page "/"
@using Syncfusion.Blazor.ProgressBar

<PageTitle>ProgressBar Demo</PageTitle>

<div style="padding: 20px;">
    <h3>Blazor ProgressBar Examples</h3>
    
    <div style="margin-bottom: 40px;">
        <h4>Linear ProgressBar</h4>
        <SfProgressBar Type="ProgressType.Linear" 
                       Value="50" 
                       Minimum="0" 
                       Maximum="100"
                       Height="60"
                       TrackThickness="12" 
                       ProgressThickness="12"
                       TrackColor="#e0e0e0"
                       ProgressColor="#0d6efd">
        </SfProgressBar>
    </div>
    
    <div style="margin-bottom: 40px;">
        <h4>Circular ProgressBar</h4>
        <SfProgressBar Type="ProgressType.Circular" 
                       Value="70" 
                       Minimum="0" 
                       Maximum="100"
                       Height="160px"
                       Width="160px"
                       TrackThickness="8" 
                       ProgressThickness="8"
                       TrackColor="#e0e0e0"
                       ProgressColor="#28a745">
        </SfProgressBar>
    </div>
</div>

Verification

Run the Application:

Visual Studio:

• Press <kbd>F5</kbd> or click Run button
• Browser opens automatically with your app

Visual Studio Code or CLI:

dotnet run

Then open browser to https://localhost:5001 (or port shown in terminal)

Expected Result:

• Linear progress bar showing 50% completion
• Circular progress bar showing 70% completion
• Both should render with smooth appearance and proper colors

Troubleshooting Installation

ProgressBar Not Visible

Issue: Component renders but nothing appears on screen

Solutions: 1. Check theme reference in index.html:

   <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

2. Verify color contrast - If background is white, try:

   <SfProgressBar ProgressColor="#0d6efd" TrackColor="#e0e0e0" ... />

3. Check height/width - Ensure adequate size:

• Linear: Height="60" minimum
• Circular: Height="160px" and Width="160px" minimum

Build Errors

Issue: Compilation errors after adding package

Solutions: 1. Clean and rebuild:

   dotnet clean
   dotnet build

2. Verify package installation in .csproj:

   <PackageReference Include="Syncfusion.Blazor.ProgressBar" Version="25.1.35" />

3. Check namespace imports in _Imports.razor:

   @using Syncfusion.Blazor.ProgressBar

Runtime Errors

Issue: "Service not registered" error

Solution: Ensure Program.cs includes:

builder.Services.AddSyncfusionBlazor();

Issue: JavaScript errors in browser console

Solution: Verify script reference in index.html:

<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

Theme Not Applied

Issue: ProgressBar appears unstyled or has wrong colors

Solutions: 1. Verify stylesheet path matches your package version 2. Clear browser cache - Hard refresh (<kbd>Ctrl</kbd>+<kbd>F5</kbd>) 3. Check CSS file exists in wwwroot/_content/Syncfusion.Blazor.Themes/ 4. Try CDN reference as alternative:

   <link href="https://cdn.syncfusion.com/blazor/25.1.35/styles/bootstrap5.css" rel="stylesheet" />

NuGet Package Errors

Issue: Cannot find or install Syncfusion packages

Solutions: 1. Add Syncfusion NuGet source (if not already added):

   dotnet nuget add source https://www.nuget.org/api/v2/ -n nuget.org

2. Clear NuGet cache:

   dotnet nuget locals all --clear

3. Retry installation:

   dotnet add package Syncfusion.Blazor.ProgressBar
   dotnet restore

Next Steps

Now that you have a working ProgressBar:

1. Explore Types - Learn about Linear vs Circular types and when to use each 2. Try States - Implement indeterminate, buffer, active, and striped states 3. Add Customization - Apply colors, segments, thickness, and corner radius 4. Implement Animations - Configure smooth progress transitions 5. Handle Events - Respond to value changes and completion 6. Add Annotations - Display custom text and labels on the progress bar

Your ProgressBar component is ready to use. Start with the basic examples above and explore advanced features as needed for your application.