Syncfusion Blazor Circular Gauge

Implementing Syncfusion Blazor CircularGauge

NuGet: Syncfusion.Blazor.CircularGauge + Syncfusion.Blazor.Themes Namespace: Syncfusion.Blazor.CircularGauge

A comprehensive guide for implementing circular gauge components in Blazor applications. CircularGauge provides radial data visualization with customizable axes, pointers, ranges, annotations, and interactive features.

When to Use This Skill

Use this skill when you need to:

• Dashboard Gauges: Create KPI dashboards with circular metric displays
• Speedometers/Tachometers: Build vehicle instrument panels or speed indicators
• Temperature/Pressure Indicators: Display environmental or industrial sensor data
• Progress Visualization: Show circular progress indicators or completion status
• Status Displays: Create color-coded status gauges with ranges (red/yellow/green zones)
• Multi-Metric Displays: Show multiple values with multiple pointers on a single gauge
• Real-Time Monitoring: Display live data updates in a circular format
• Interactive Gauges: Allow users to adjust values by dragging pointers
• Radial KPIs: Visualize performance metrics in a radial/circular layout

Component Overview

The Syncfusion Blazor CircularGauge (SfCircularGauge) is a data visualization component that displays quantitative information in a circular arc. It supports multiple pointer types, color-coded ranges, custom annotations, legends, and rich interactivity.

Key Capabilities:

• Multiple pointer types (needle, range bar, marker)
• Configurable axes with custom ranges and angles
• Color-coded ranges for visual zones
• Annotations with text, images, or HTML content
• Tooltips and user interactions
• Pointer dragging for value adjustment
• Legends for ranges
• Animations and transitions
• Globalization and RTL support
• Accessibility features (WCAG compliant)
• Print and export functionality

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Read this reference when you need to:

• Install NuGet packages and set up the component
• Configure services and CSS/theme imports
• Create your first basic circular gauge
• Understand project structure and prerequisites
• Run the application with CircularGauge

Axes Configuration

📄 Read: references/axes-configuration.md

Read this reference when you need to:

• Customize axis appearance (line width, color, background)
• Set minimum and maximum values for the scale
• Configure axis radius and positioning
• Set start and end angles (semi-circle, quarter-circle, custom arcs)
• Configure axis direction (clockwise/anticlockwise)
• Customize labels (format, font, position, rotation, custom text)
• Configure major and minor ticks (intervals, size, styling)
• Implement multiple axes on a single gauge

Pointers

📄 Read: references/pointers.md

Read this reference when you need to:

• Add needle pointers with customizable appearance
• Configure needle cap/knob and tail styling
• Implement range bar pointers with gradients
• Add marker pointers (circle, rectangle, triangle, diamond, image)
• Set pointer values and animate pointer movement
• Use multiple pointers of different types on one axis
• Enable pointer dragging for interactive value adjustment
• Position and layer pointers correctly

Ranges

📄 Read: references/ranges.md

Read this reference when you need to:

• Create color-coded zones on the gauge (e.g., red/yellow/green)
• Define range start and end values
• Customize range colors, gradients, and styling
• Configure range positioning (radius and thickness)
• Implement multiple overlapping ranges
• Add rounded corners to ranges
• Use ranges for status indicators or zone marking

Annotations

📄 Read: references/annotations.md

Read this reference when you need to:

• Add text annotations to display values or labels
• Insert HTML content or images as annotations
• Position annotations using angle, radius, or X/Y coordinates
• Style annotations (font, color, background, borders)
• Create multiple annotations on a single gauge
• Display dynamic content (e.g., current pointer value)
• Add conditional annotations based on gauge state
• Center labels showing gauge readings

Legend

📄 Read: references/legend.md

Read this reference when you need to:

• Enable legends for gauge ranges
• Position legends (top, bottom, left, right, custom)
• Customize legend appearance (font, colors, shapes, borders)
• Implement interactive legends with toggle functionality
• Create custom legend templates
• Handle legend click events

Appearance and Styling

📄 Read: references/appearance.md

Read this reference when you need to:

• Apply built-in themes (Material, Bootstrap, Fluent, etc.)
• Customize colors, backgrounds, and borders
• Configure gauge dimensions (width, height, responsive sizing)
• Add and style gauge titles
• Configure center X/Y positioning
• Set up animations (duration, easing)
• Implement print and export functionality (image/PDF)
• Apply custom styling and CSS classes

User Interaction

📄 Read: references/user-interaction.md

Read this reference when you need to:

• Enable and customize tooltips
• Create custom tooltip templates
• Enable pointer dragging for user input
• Handle drag events (DragStart, DragMove, DragEnd)
• Implement gauge events (Load, Loaded, AnimationComplete, etc.)
• Handle AxisLabelRendering and TooltipRendering events
• Restrict pointer drag ranges
• Create interactive gauges (adjustable temperature, speed controls)

Globalization

📄 Read: references/globalization.md

Read this reference when you need to:

• Format numbers based on locale
• Implement custom number patterns
• Localize labels and text
• Enable RTL (right-to-left) support
• Format currency or date/time values
• Integrate CLDR data for internationalization

Advanced Features

📄 Read: references/advanced-features.md

Read this reference when you need to:

• Use methods (SetPointerValue, SetAnnotationValue, Refresh, Print, Export)
• Update pointer values dynamically at runtime
• Optimize performance for complex gauges
• Place gauges inside other components (grids, dashboards, tabs)
• Implement real-time data updates with timers or SignalR
• Configure accessibility features (WCAG, keyboard navigation, screen readers)
• Implement responsive design patterns
• Handle server-side vs WebAssembly considerations
• Test and troubleshoot complex gauge scenarios

Quick Start Example

Here's a basic circular gauge with a needle pointer:

@page "/circular-gauge"
@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="120">
            <CircularGaugePointers>
                <CircularGaugePointer Value="65" Color="#007DD1">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Prerequisites: 1. Install Syncfusion.Blazor.CircularGauge and Syncfusion.Blazor.Themes NuGet packages 2. Register services: builder.Services.AddSyncfusionBlazor(); 3. Import theme CSS in App.razor or index.html

Common Patterns

Pattern 1: Speedometer Gauge

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="120" StartAngle="220" EndAngle="140">
            <CircularGaugeAxisLabelStyle>
                <CircularGaugeAxisLabelFont Size="12px"></CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisLineStyle Width="10" Color="#E0E0E0">
            </CircularGaugeAxisLineStyle>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="40" Color="#30B32D"></CircularGaugeRange>
                <CircularGaugeRange Start="40" End="80" Color="#FFDD00"></CircularGaugeRange>
                <CircularGaugeRange Start="80" End="120" Color="#F03E3E"></CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65" Radius="60%" Color="#757575">
                    <CircularGaugePointerAnimation Enable="true" Duration="1500">
                    </CircularGaugePointerAnimation>
                    <CircularGaugeCap Radius="7">
                        <CircularGaugeCapBorder Width="3" Color="#757575">
                        </CircularGaugeCapBorder>
                    </CircularGaugeCap>
                    <CircularGaugeNeedleTail Length="18%" Color="#757575">
                    </CircularGaugeNeedleTail>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Pattern 2: Temperature Indicator

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="-20" Maximum="50">
            <CircularGaugeAxisLineStyle Width="0">
            </CircularGaugeAxisLineStyle>
            <CircularGaugeAxisMajorTicks Height="0"></CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks Height="0"></CircularGaugeAxisMinorTicks>
            <CircularGaugeAxisLabelStyle>
                <CircularGaugeAxisLabelFont Size="0px"></CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="-20" End="0" Color="#6495ED" Radius="90%" StartWidth="30" EndWidth="30">
                </CircularGaugeRange>
                <CircularGaugeRange Start="0" End="20" Color="#FFA500" Radius="90%" StartWidth="30" EndWidth="30">
                </CircularGaugeRange>
                <CircularGaugeRange Start="20" End="50" Color="#FF4500" Radius="90%" StartWidth="30" EndWidth="30">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="22" Radius="0%" Type="PointerType.Marker" 
                                      MarkerShape="GaugeShape.Triangle" MarkerHeight="20" MarkerWidth="20" 
                                      Color="#333">
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="0" Radius="0%" ZIndex="1">
                    <ContentTemplate>
                        <div style="font-size:24px;font-weight:bold;color:#333;">22°C</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Pattern 3: Multi-Pointer Gauge

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugePointers>
                <CircularGaugePointer Value="30" Color="#007DD1" PointerWidth="8" Radius="70%">
                </CircularGaugePointer>
                <CircularGaugePointer Value="60" Color="#E5CE20" PointerWidth="8" Radius="80%">
                </CircularGaugePointer>
                <CircularGaugePointer Value="90" Color="#F44336" PointerWidth="8" Radius="90%">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Pattern 4: Range-Based Status Gauge with Legend

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeLegendSettings Visible="true" Position="Syncfusion.Blazor.CircularGauge.LegendPosition.Bottom">
    </CircularGaugeLegendSettings>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="33" Color="#30B32D" LegendText="Good">
                </CircularGaugeRange>
                <CircularGaugeRange Start="33" End="66" Color="#FFDD00" LegendText="Warning">
                </CircularGaugeRange>
                <CircularGaugeRange Start="66" End="100" Color="#F03E3E" LegendText="Critical">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="75" Type="PointerType.RangeBar" Radius="60%" 
                                      PointerWidth="15" Color="#F03E3E">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Key Props and Configuration

API Reference (summary)

Namespace / Import

• @using Syncfusion.Blazor.CircularGauge

Component: SfCircularGauge

Core Properties

• AllowImageExport (bool)
• AllowMargin (bool)
• AllowPdfExport (bool)
• AllowPrint (bool)
• AnimationDuration (double) — animation duration in milliseconds
• Background (string)
• CenterX (string)
• CenterY (string)
• Description (string)
• EnableGroupingSeparator (bool)
• EnablePointerDrag (bool)
• EnableRangeDrag (bool)
• Height (string)
• ID (string)
• MoveToCenter (bool)
• TabIndex (int)
• Theme (enum)
• Title (string)
• Width (string)

Important Methods

• Task<string> ExportAsync(ExportType type, string fileName, PdfPageOrientation? orientation = null, bool allowDownload = true)
• Task PrintAsync()
• Task RefreshAsync()
• Task SetAnnotationValueAsync(int axisIndex, int annotationIndex, string content)
• Task SetPointerValueAsync(int axisIndex, int pointerIndex, double pointerValue)
• void SetRangeValue(int axisIndex, int rangeIndex, double start, double end)
• void UpdateChildProperties(string key, object keyValue)

Events (common)

• AnimationCompleted (AnimationCompleteEventArgs)
• AnnotationRendering (AnnotationRenderEventArgs)
• AxisLabelRendering (AxisLabelRenderEventArgs)
• Loaded / OnLoad (LoadedEventArgs)
• OnGaugeMouseDown / OnGaugeMouseMove / OnGaugeMouseUp / OnGaugeMouseLeave (MouseEventArgs)
• OnDrag, OnDragStart, OnDragEnd (PointerDragEventArgs)
• OnPrint (PrintEventArgs)
• OnRadiusCalculate (RadiusCalculateEventArgs)
• Resizing (ResizeEventArgs)
• TooltipRendering (TooltipRenderEventArgs)

Child Tags and Key Properties

• CircularGaugeAnnotation — Content, Angle, Radius, AutoAngle
• CircularGaugeAxes — collection of CircularGaugeAxis
• CircularGaugeAxis — Background, Direction, EndAngle, StartAngle, Maximum, Minimum, Radius
• CircularGaugeBorder — Color, Width
• CircularGaugeLegendSettings — Visible, Position, Shape, ToggleVisibility
• CircularGaugeMargin — Top, Bottom, Left, Right
• CircularGaugePointer — Type, Value, Color, MarkerShape, Position, PointerWidth, Radius
• CircularGaugeRange — Start, End, Color, StartWidth, EndWidth, Radius
• CircularGaugeTooltipSettings — Enable, Fill, Format, ShowAtMousePosition

Styling CSS classes

• e-circulargauge
• e-gauge-axis
• e-gauge-pointer
• e-gauge-range
• e-gauge-annotation

Typical Usage Snippet

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Title="Basic Circular Gauge" Height="400px" Width="400px">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100" StartAngle="200" EndAngle="160">
            <CircularGaugePointers>
                <CircularGaugePointer Value="65" Color="#007DD1" PointerWidth="8">
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="50" Color="#3A5998" StartWidth="10" EndWidth="10">
                </CircularGaugeRange>
                <CircularGaugeRange Start="50" End="100" Color="#33BCDA" StartWidth="10" EndWidth="10">
                </CircularGaugeRange>
            </CircularGaugeRanges>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Common Use Cases

1. Dashboard KPI Displays: Show business metrics like sales performance, customer satisfaction scores, or completion percentages 2. Vehicle Instruments: Create speedometers, tachometers, fuel gauges, or battery indicators 3. Environmental Monitoring: Display temperature, humidity, pressure, or air quality readings 4. Industrial Controls: Show machine status, pressure levels, RPM, or load percentages 5. Health & Fitness: Visualize heart rate, step count, calorie burn, or workout intensity 6. Resource Utilization: Display CPU usage, memory consumption, disk space, or network bandwidth 7. Progress Tracking: Show project completion, task progress, or milestone achievement 8. Quality Metrics: Display defect rates, test pass rates, or compliance scores 9. Financial Indicators: Show portfolio performance, risk levels, or budget utilization 10. Interactive Settings: Allow users to adjust thermostat settings, volume levels, or brightness controls

Related Skills

• Implementing Linear Gauges - For horizontal/vertical linear gauge displays

---

Next Steps: Read the appropriate reference file based on your implementation needs. Start with getting-started.md for new implementations, or navigate directly to specific feature documentation.

Advanced Features

Table of Contents

• Overview
• Methods
• Accessibility
• Real-Time Data Updates
• Placing Gauges Inside Other Components
• Performance Optimization
• Testing and Debugging

Overview

This guide covers advanced CircularGauge features including programmatic control via methods, accessibility compliance, real-time data integration, embedding gauges in complex layouts, and performance optimization techniques.

Methods

The CircularGauge provides methods for programmatic control of gauge behavior and values.

SetPointerValueAsync

Update pointer values programmatically with animation.

Syntax:

await gaugeInstance.SetPointerValueAsync(axisIndex, pointerIndex, value);

Example:

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="@pointerValue">
                    <CircularGaugePointerAnimation Enable="true" Duration="1000">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<button @onclick="UpdatePointer">Update Pointer</button>

@code {
    SfCircularGauge gauge;
    private double pointerValue = 50;
    
    async Task UpdatePointer()
    {
        double newValue = new Random().Next(0, 100);
        await gauge.SetPointerValueAsync(0, 0, newValue);
        pointerValue = newValue;
    }
}

Parameters:

• axisIndex (int): Zero-based index of the axis (0 for first axis)
• pointerIndex (int): Zero-based index of the pointer (0 for first pointer)
• value (double): New pointer value

Use Cases:

• Real-time sensor data updates
• User input validation and adjustment
• Animated value transitions
• Dashboard updates from API calls

SetAnnotationValueAsync

Update annotation content dynamically.

Syntax:

await gaugeInstance.SetAnnotationValueAsync(axisIndex, annotationIndex, content);

Example:

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="@currentValue">
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="0" Radius="0%">
                    <ContentTemplate>
                        <div id="annotation-value">@currentValue%</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<button @onclick="UpdateAnnotation">Update Label</button>

@code {
    SfCircularGauge gauge;
    private double currentValue = 65;
    
    async Task UpdateAnnotation()
    {
        currentValue = new Random().Next(0, 100);
        await gauge.SetAnnotationValueAsync(0, 0, $"<div>{currentValue}%</div>");
        await gauge.SetPointerValueAsync(0, 0, currentValue);
    }
}

Parameters:

• axisIndex (int): Zero-based index of the axis
• annotationIndex (int): Zero-based index of the annotation
• content (string): New HTML content for the annotation

Use Cases:

• Dynamic label updates
• Status message changes
• Custom formatted values
• Conditional content display

SetRangeValue

Adjust range boundaries programmatically.

Syntax:

gaugeInstance.SetRangeValue(axisIndex, rangeIndex, start, end);

Example:

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeRanges>
                <CircularGaugeRange 
                    Start="@redZoneStart" 
                    End="@redZoneEnd" 
                    Color="#FF6B6B">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="75">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<button @onclick="AdjustRedZone">Adjust Danger Zone</button>

@code {
    SfCircularGauge gauge;
    private double redZoneStart = 70;
    private double redZoneEnd = 100;
    
    void AdjustRedZone()
    {
        redZoneStart = 60;
        redZoneEnd = 100;
        gauge.SetRangeValue(0, 0, redZoneStart, redZoneEnd);
    }
}

Parameters:

• axisIndex (int): Zero-based index of the axis
• rangeIndex (int): Zero-based index of the range
• start (double): New start value
• end (double): New end value

Use Cases:

• Dynamic threshold adjustments
• User-defined safe zones
• Conditional range updates
• Configuration-based ranges

RefreshAsync

Force gauge re-render when container size changes.

Syntax:

await gaugeInstance.RefreshAsync();

Example:

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge" Width="@gaugeWidth" Height="@gaugeHeight">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<button @onclick="ResizeGauge">Resize Gauge</button>

@code {
    SfCircularGauge gauge;
    private string gaugeWidth = "300px";
    private string gaugeHeight = "300px";
    
    async Task ResizeGauge()
    {
        gaugeWidth = "500px";
        gaugeHeight = "500px";
        StateHasChanged();
        await Task.Delay(100); // Wait for DOM update
        await gauge.RefreshAsync();
    }
}

Use Cases:

• Responsive design updates
• Container resize handling
• Tab/Dialog visibility changes
• Dynamic layout adjustments

Complete Methods Example

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugePointers>
                <CircularGaugePointer Value="@temperature">
                    <CircularGaugePointerAnimation Enable="true" Duration="500">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeRanges>
                <CircularGaugeRange 
                    Start="@safeStart" 
                    End="@safeEnd" 
                    Color="#30B32D">
                </CircularGaugeRange>
                <CircularGaugeRange 
                    Start="@dangerStart" 
                    End="@dangerEnd" 
                    Color="#FF6B6B">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="0" Radius="0%">
                    <ContentTemplate>
                        <div>@temperature°C</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<div>
    <button @onclick="SimulateSensorUpdate">Simulate Sensor</button>
    <button @onclick="AdjustThresholds">Adjust Thresholds</button>
</div>

@code {
    SfCircularGauge gauge;
    private double temperature = 22;
    private double safeStart = 18, safeEnd = 26;
    private double dangerStart = 26, dangerEnd = 100;
    
    async Task SimulateSensorUpdate()
    {
        temperature = new Random().Next(15, 35);
        await gauge.SetPointerValueAsync(0, 0, temperature);
        await gauge.SetAnnotationValueAsync(0, 0, $"<div>{temperature}°C</div>");
    }
    
    void AdjustThresholds()
    {
        safeStart = 20;
        safeEnd = 24;
        dangerStart = 24;
        dangerEnd = 100;
        gauge.SetRangeValue(0, 0, safeStart, safeEnd);
        gauge.SetRangeValue(0, 1, dangerStart, dangerEnd);
    }
}

Accessibility

The CircularGauge is designed for accessibility compliance.

WCAG 2.2 AA Compliance

Standards Supported:

• WCAG 2.2 Level AA: Yes
• Section 508: Partial support
• Screen Reader Support: Yes
• Right-to-Left Support: Yes
• Color Contrast: Must be manually ensured
• Keyboard Navigation: Not applicable (read-only visualization)

Screen Reader Support

The gauge automatically includes WAI-ARIA attributes:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="75" Description="Temperature gauge at 75 degrees">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Generated HTML includes:

• role="region": Identifies gauge as a landmark
• aria-label: Provides accessible name
• aria-describedby: Links to description text

Best Practices for Accessibility

1. Provide Meaningful Titles

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Title="Server CPU Usage">
    <CircularGaugeTitleStyle Size="20px" />
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

2. Ensure Color Contrast

• Use high-contrast colors (4.5:1 ratio minimum)
• Don't rely solely on color for information
• Add text labels alongside color indicators

<CircularGaugeRange Start="0" End="50" Color="#30B32D">
</CircularGaugeRange>
<CircularGaugeAnnotation Angle="45" Radius="70%">
    <ContentTemplate>
        <div>Safe (0-50)</div>
    </ContentTemplate>
</CircularGaugeAnnotation>

3. Add Text Alternatives

@using Syncfusion.Blazor.CircularGauge
<div aria-label="Temperature gauge showing 22 degrees Celsius, within safe range of 18-26 degrees">
    <SfCircularGauge>
        <CircularGaugeAxes>
            <CircularGaugeAxis Minimum="0" Maximum="40">
                <CircularGaugePointers>
                    <CircularGaugePointer Value="22">
                    </CircularGaugePointer>
                </CircularGaugePointers>
            </CircularGaugeAxis>
        </CircularGaugeAxes>
    </SfCircularGauge>
</div>
<p class="sr-only">Current temperature: 22°C (Safe range: 18-26°C)</p>

4. Support RTL for International Users

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="60">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Real-Time Data Updates

Integrate CircularGauge with live data sources.

SignalR Integration

@using Microsoft.AspNetCore.SignalR.Client
@using Syncfusion.Blazor.CircularGauge
@inject NavigationManager Navigation
@implements IAsyncDisposable

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugeAxisLabelStyle Format="{value}%">
            </CircularGaugeAxisLabelStyle>
            <CircularGaugePointers>
                <CircularGaugePointer Value="@cpuUsage">
                    <CircularGaugePointerAnimation Enable="true" Duration="300">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="60" Color="#30B32D">
                </CircularGaugeRange>
                <CircularGaugeRange Start="60" End="85" Color="#FFC107">
                </CircularGaugeRange>
                <CircularGaugeRange Start="85" End="100" Color="#FF6B6B">
                </CircularGaugeRange>
            </CircularGaugeRanges>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<div>CPU Usage: @cpuUsage%</div>

@code {
    SfCircularGauge gauge;
    private HubConnection hubConnection;
    private double cpuUsage = 0;
    
    protected override async Task OnInitializedAsync()
    {
        hubConnection = new HubConnectionBuilder()
            .WithUrl(Navigation.ToAbsoluteUri("/serverhub"))
            .Build();
        
        hubConnection.On<double>("ReceiveCPUUpdate", async (usage) =>
        {
            cpuUsage = usage;
            await gauge.SetPointerValueAsync(0, 0, cpuUsage);
            StateHasChanged();
        });
        
        await hubConnection.StartAsync();
    }
    
    public async ValueTask DisposeAsync()
    {
        if (hubConnection is not null)
        {
            await hubConnection.DisposeAsync();
        }
    }
}

Timer-Based Updates

@implements IDisposable
@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="120">
            <CircularGaugePointers>
                <CircularGaugePointer Value="@speed">
                    <CircularGaugePointerAnimation Enable="true" Duration="500">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    SfCircularGauge gauge;
    private System.Threading.Timer timer;
    private double speed = 0;
    private Random random = new Random();
    
    protected override void OnInitialized()
    {
        timer = new System.Threading.Timer(async _ =>
        {
            speed = random.Next(40, 100);
            await InvokeAsync(async () =>
            {
                await gauge.SetPointerValueAsync(0, 0, speed);
                StateHasChanged();
            });
        }, null, 0, 2000); // Update every 2 seconds
    }
    
    public void Dispose()
    {
        timer?.Dispose();
    }
}

HTTP Polling

@inject HttpClient Http
@implements IDisposable
@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge @ref="gauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugePointers>
                <CircularGaugePointer Value="@temperatureValue">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    SfCircularGauge gauge;
    private System.Threading.Timer timer;
    private double temperatureValue = 20;
    
    protected override void OnInitialized()
    {
        timer = new System.Threading.Timer(async _ =>
        {
            var data = await Http.GetFromJsonAsync<SensorData>("api/sensors/temperature");
            temperatureValue = data.Value;
            await InvokeAsync(async () =>
            {
                await gauge.SetPointerValueAsync(0, 0, temperatureValue);
                StateHasChanged();
            });
        }, null, 0, 5000); // Poll every 5 seconds
    }
    
    public void Dispose()
    {
        timer?.Dispose();
    }
    
    public class SensorData
    {
        public double Value { get; set; }
    }
}

Placing Gauges Inside Other Components

Special considerations when embedding gauges in dynamic containers.

Dashboard Layout

Use boolean flag and RefreshAsync for proper rendering:

@using Syncfusion.Blazor.Layouts
@using Syncfusion.Blazor.CircularGauge

<SfDashboardLayout AllowResizing="true" Columns="20">
    <DashboardLayoutEvents Created="OnCreated" OnWindowResize="OnResize">
    </DashboardLayoutEvents>
    <DashboardLayoutPanels>
        <DashboardLayoutPanel Row="0" Column="0" SizeX="10" SizeY="5">
            <HeaderTemplate><div>CPU Usage</div></HeaderTemplate>
            <ContentTemplate>
                    <SfCircularGauge @ref="gauge" Width="100%" Height="100%">
                        <CircularGaugeAxes>
                            <CircularGaugeAxis>
                                <CircularGaugePointers>
                                    <CircularGaugePointer Value="65">
                                    </CircularGaugePointer>
                                </CircularGaugePointers>
                            </CircularGaugeAxis>
                        </CircularGaugeAxes>
                    </SfCircularGauge>
            </ContentTemplate>
        </DashboardLayoutPanel>
    </DashboardLayoutPanels>
</SfDashboardLayout>

@code {
    SfCircularGauge gauge;
    private System.Threading.Timer resizeTimer;
    
    async void OnCreated()
    {
        await Task.Yield();
    }
    
    async Task OnResize(ResizeArgs args)
    {
        if (resizeTimer != null)
        {
            resizeTimer.Dispose();
        }
        resizeTimer = new System.Threading.Timer(async _ =>
        {
            await InvokeAsync(async () =>
            {
                await gauge.RefreshAsync();
            });
        }, null, 500, System.Threading.Timeout.Infinite);
    }

    
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await Task.Delay(50);
            if (gauge != null)
            {
                await gauge.RefreshAsync();
            }
        }
    }

}

Tab Component

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.CircularGauge

<SfTab>
    <TabEvents Created="OnTabCreated"></TabEvents>
    <TabItems>
        <TabItem>
            <ChildContent>
                <TabHeader Text="Gauge"></TabHeader>
            </ChildContent>
            <ContentTemplate>
                @if (isInitialRender)
                {
                    <SfCircularGauge>
                        <CircularGaugeAxes>
                            <CircularGaugeAxis>
                                <CircularGaugePointers>
                                    <CircularGaugePointer Value="75">
                                    </CircularGaugePointer>
                                </CircularGaugePointers>
                            </CircularGaugeAxis>
                        </CircularGaugeAxes>
                    </SfCircularGauge>
                }
            </ContentTemplate>
        </TabItem>
    </TabItems>
</SfTab>

@code {
    private bool isInitialRender = false;
    
    void OnTabCreated()
    {
        isInitialRender = true;
    }
}

Dialog Component

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.CircularGauge

<SfDialog @bind-Visible="dialogVisible" Width="400px" Height="400px" EnableResize="true">
    <DialogEvents Opened="OnDialogOpened" Closed="OnDialogClosed" OnResizeStop="OnDialogResize">
    </DialogEvents>
    <DialogTemplates>
        <Header>Gauge</Header>
        <Content>
            @if (isInitialRender)
            {
                <SfCircularGauge @ref="gauge" Width="100%" Height="100%">
                    <CircularGaugeAxes>
                        <CircularGaugeAxis>
                            <CircularGaugePointers>
                                <CircularGaugePointer Value="50">
                                </CircularGaugePointer>
                            </CircularGaugePointers>
                        </CircularGaugeAxis>
                    </CircularGaugeAxes>
                </SfCircularGauge>
            }
        </Content>
    </DialogTemplates>
</SfDialog>

@code {
    SfCircularGauge gauge;
    private bool dialogVisible = true;
    private bool isInitialRender = false;
    
    void OnDialogOpened()
    {
        isInitialRender = true;
    }
    
    void OnDialogClosed()
    {
        isInitialRender = false;
    }
    
    async Task OnDialogResize(Microsoft.AspNetCore.Components.Web.MouseEventArgs args)
    {
        await Task.Delay(100);
        await gauge.RefreshAsync();
    }
}

Accordion Component

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.CircularGauge

<SfAccordion>
    <AccordionEvents Expanded="OnAccordionExpanded">
    </AccordionEvents>
    <AccordionItems>
        <AccordionItem Expanded="true">
            <HeaderTemplate>Gauge Panel</HeaderTemplate>
            <ContentTemplate>
                    <SfCircularGauge @ref="gauge">
                        <CircularGaugeAxes>
                            <CircularGaugeAxis>
                                <CircularGaugePointers>
                                    <CircularGaugePointer Value="80">
                                    </CircularGaugePointer>
                                </CircularGaugePointers>
                            </CircularGaugeAxis>
                        </CircularGaugeAxes>
                    </SfCircularGauge>
            </ContentTemplate>
        </AccordionItem>
    </AccordionItems>
</SfAccordion>

@code {
    SfCircularGauge gauge;
    
    async Task OnAccordionExpanded(ExpandedEventArgs args)
    {
        await Task.Delay(100);
        await gauge.RefreshAsync();
    }
}

Performance Optimization

Disable Unnecessary Features

@using Syncfusion.Blazor.CircularGauge
<!-- Disable animation for rapidly updating gauges -->
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="20">
                    <CircularGaugePointerAnimation Enable="false">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Debounce Rapid Updates

private System.Threading.Timer debounceTimer;
private double pendingValue;

void UpdateGaugeValue(double newValue)
{
    pendingValue = newValue;
    
    if (debounceTimer != null)
    {
        debounceTimer.Dispose();
    }
    
    debounceTimer = new System.Threading.Timer(async _ =>
    {
        await InvokeAsync(async () =>
        {
            await gauge.SetPointerValueAsync(0, 0, pendingValue);
            StateHasChanged();
        });
    }, null, 300, System.Threading.Timeout.Infinite); // 300ms debounce
}

Use Appropriate Axis Ranges

@using Syncfusion.Blazor.CircularGauge
<!-- Bad: Excessive precision -->
<CircularGaugeAxis Minimum="0" Maximum="100">
    <CircularGaugeAxisMajorTicks Interval="1" />
    <CircularGaugeAxisMinorTicks Interval="0.1" />
</CircularGaugeAxis>

<!-- Good: Reasonable precision -->
<CircularGaugeAxis Minimum="0" Maximum="100">
    <CircularGaugeAxisMajorTicks Interval="10" />
    <CircularGaugeAxisMinorTicks Interval="5" />
</CircularGaugeAxis>

Testing and Debugging

Unit Testing Gauge Updates

[Fact]
public async Task UpdatePointer_ShouldChangeValue()
{
    // Arrange
    var ctx = new TestContext();
    var component = ctx.RenderComponent<GaugeComponent>();
    var gauge = component.Find("SfCircularGauge");
    
    // Act
    await component.Instance.UpdatePointerValue(75);
    
    // Assert
    Assert.Equal(75, component.Instance.CurrentValue);
}

Browser DevTools Inspection

@using Syncfusion.Blazor.CircularGauge

<!-- Add ID for debugging -->
<SfCircularGauge ID="debugGauge">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="@debugValue">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    private double debugValue = 50;
    
    protected override void OnAfterRender(bool firstRender)
    {
        Console.WriteLine($"Gauge rendered with value: {debugValue}");
    }
}

Common Debugging Scenarios

Gauge not rendering:

• Check browser console for errors
• Verify Syncfusion license is configured
• Ensure CSS is loaded
• Verify component reference is not null

Values not updating:

• Check SetPointerValueAsync is awaited
• Verify StateHasChanged() is called
• Ensure axis min/max accommodate values
• Check for JavaScript errors

Performance issues:

• Disable animation for real-time data
• Reduce update frequency
• Simplify gauge design (fewer ticks, ranges)
• Profile with browser DevTools

Best Practices Summary

Methods

• Always await async methods
• Use SetPointerValueAsync for animated updates
• Call RefreshAsync after container resize
• Index parameters are zero-based

Accessibility

• Provide meaningful titles
• Ensure 4.5:1 color contrast
• Add text alternatives
• Support RTL for international users

Real-Time Data

• Use SignalR for server push
• Debounce rapid updates (300-500ms)
• Disable animation for frequent updates
• Handle connection errors gracefully

Container Integration

• Use boolean flag for initial render
• Call Task.Yield() before setting flag
• Refresh on resize/expand events
• Add 100-500ms delay before refresh

Performance

• Disable unnecessary animations
• Use reasonable axis precision
• Debounce rapid updates
• Profile and optimize as needed

Circular Gauge Annotations Reference

Table of Contents

• Overview
• Creating Annotations
• Content Types
• Positioning Annotations
• Multiple Annotations
• Styling and Customization
• Dynamic Annotations
• Use Cases
• Best Practices
• Troubleshooting

Overview

Annotations in Circular Gauge allow you to overlay custom content, such as text, HTML, shapes, or images, at specific positions on the gauge. They provide a powerful way to add contextual information, labels, instructions, or decorative elements that enhance the gauge's readability and visual appeal.

Annotations are highly flexible and can be positioned using polar coordinates (angle and radius) or Cartesian coordinates (X and Y offsets), making them suitable for a wide variety of scenarios.

Creating Annotations

Basic Annotation

Annotations are defined using the CircularGaugeAnnotations collection within an axis. Each annotation can contain custom content through the ContentTemplate.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Height="250px" Width="250px">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="50"></CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="195" ZIndex="1">
                    <ContentTemplate>
                        <div class="custom-annotation">50</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style type="text/css">
    .custom-annotation {
        color: white;
        background-color: blue;
        height: 30px;
        width: 30px;
        border-radius: 15px;
        padding: 4px 0 0 6px;
        font-weight: bold;
    }
</style>

Annotation Properties

Essential Properties:

• ContentTemplate - Defines the HTML content to display
• Content - Simple text content (alternative to ContentTemplate)
• Angle - Angular position in degrees (0-360)
• Radius - Radial distance from center (percentage or pixels)
• ZIndex - Stacking order for overlapping annotations
• AutoAngle - Automatically rotates annotation based on angle
• TextStyle - Font and text styling options

Content Types

Text Annotations

Simple text content using the Content property.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Content="Speed" 
                                         Angle="180" 
                                         Radius="50%" 
                                         ZIndex="1">
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

HTML Annotations

Rich HTML content with styling through ContentTemplate.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Height="250px" Width="250px">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="30%" ZIndex="1">
                    <ContentTemplate>
                        <div style="font-size: 16px; color: #666; font-weight: bold;">
                            <span style="color: #007bff;">Current Speed</span><br/>
                            <span style="font-size: 24px; color: #28a745;">65</span>
                            <span style="font-size: 14px;">km/h</span>
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Image Annotations

Include images as annotations for icons or logos.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="0%" ZIndex="1">
                    <ContentTemplate>
                        <div>
                            <img src="logo.png" width="50" height="50" alt="Logo"/>
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Styled Containers

Create custom styled containers for complex layouts.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="25%" ZIndex="1">
                    <ContentTemplate>
                        <div class="gauge-card">
                            <div class="gauge-title">Temperature</div>
                            <div class="gauge-value">72°F</div>
                            <div class="gauge-status">Normal</div>
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style>
    .gauge-card {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        padding: 15px;
        border-radius: 10px;
        color: white;
        text-align: center;
        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
    }
    
    .gauge-title {
        font-size: 12px;
        opacity: 0.9;
        margin-bottom: 5px;
    }
    
    .gauge-value {
        font-size: 24px;
        font-weight: bold;
        margin-bottom: 5px;
    }
    
    .gauge-status {
        font-size: 10px;
        opacity: 0.8;
    }
</style>

Positioning Annotations

Angular Positioning

Use the Angle property to position annotations around the gauge circumference.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Height="250px" Width="250px">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="50"></CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="90"
                                         Radius="110%"
                                         ZIndex="1">
                    <ContentTemplate>
                        <div class="custom-annotation">50</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style type="text/css">
    .custom-annotation {
        color: white;
        background-color: blue;
        height: 30px;
        width: 30px;
        border-radius: 15px;
        padding: 4px 0 0 6px;
        font-weight: bold;
    }
</style>

Angle Reference:

• 0° - Right (3 o'clock position)
• 90° - Bottom (6 o'clock position)
• 180° - Left (9 o'clock position)
• 270° - Top (12 o'clock position)

Radial Positioning

Use the Radius property to control distance from the gauge center.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <!-- Center annotation -->
                <CircularGaugeAnnotation Angle="180" Radius="0%" ZIndex="1">
                    <ContentTemplate>
                        <div>Center</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
                
                <!-- Middle annotation -->
                <CircularGaugeAnnotation Angle="180" Radius="50%" ZIndex="1">
                    <ContentTemplate>
                        <div>Middle</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
                
                <!-- Outer annotation -->
                <CircularGaugeAnnotation Angle="180" Radius="120%" ZIndex="1">
                    <ContentTemplate>
                        <div>Outside</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Radius Tips:

• 0% - Gauge center
• 50% - Halfway to axis
• 100% - On the axis
• >100% - Outside the gauge

Z-Index for Layering

Control stacking order with ZIndex for overlapping annotations.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <!-- Background annotation -->
                <CircularGaugeAnnotation Angle="180" Radius="30%" ZIndex="0">
                    <ContentTemplate>
                        <div style="background: lightgray; padding: 20px;">
                            Background
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
                
                <!-- Foreground annotation -->
                <CircularGaugeAnnotation Angle="180" Radius="30%" ZIndex="2">
                    <ContentTemplate>
                        <div style="background: blue; color: white; padding: 10px;">
                            Foreground
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Multiple Annotations

Create complex visualizations with multiple annotations at different positions.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Height="250px" Width="250px">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="35"
                                    End="70"
                                    Color="blue"
                                    Opacity="0.2">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="50"></CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <!-- Title annotation -->
                <CircularGaugeAnnotation Angle="325" Radius="150%" ZIndex="1">
                    <ContentTemplate>
                        <div class="custom-annotation">Speed to get higher mileage</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
                
                <!-- Value annotation -->
                <CircularGaugeAnnotation Angle="195" ZIndex="1">
                    <ContentTemplate>
                        <div class="speed">50</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style type="text/css">
    .speed {
        color: white;
        background-color: blue;
        height: 30px;
        width: 30px;
        border-radius: 15px;
        padding: 4px 0 0 6px;
        font-weight: bold;
    }

    .custom-annotation {
        background-color: lightgray;
        width: 100%;
        padding: 1px;
    }
</style>

Circular Label Annotations

Position labels around the gauge perimeter for a clock or compass effect.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Content="N" Angle="270" Radius="120%" ZIndex="1">
                </CircularGaugeAnnotation>
                <CircularGaugeAnnotation Content="E" Angle="0" Radius="120%" ZIndex="1">
                </CircularGaugeAnnotation>
                <CircularGaugeAnnotation Content="S" Angle="90" Radius="120%" ZIndex="1">
                </CircularGaugeAnnotation>
                <CircularGaugeAnnotation Content="W" Angle="180" Radius="120%" ZIndex="1">
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Styling and Customization

Text Style Properties

When using the Content property, apply text styling through CircularGaugeAnnotationTextStyle.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Content="Speed" 
                                         Angle="180" 
                                         Radius="50%" 
                                         ZIndex="1">
                    <CircularGaugeAnnotationTextStyle Size="20px"
                                                      Color="#007bff"
                                                      FontWeight="bold"
                                                      FontFamily="Arial">
                    </CircularGaugeAnnotationTextStyle>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

CSS Styling for ContentTemplate

Apply comprehensive styling through CSS classes.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="30%" ZIndex="1">
                    <ContentTemplate>
                        <div class="annotation-box">
                            <i class="icon-speedometer"></i>
                            <span class="value">65</span>
                            <span class="unit">mph</span>
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style>
    .annotation-box {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 5px;
        padding: 10px;
        background: rgba(255, 255, 255, 0.9);
        border-radius: 8px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
    }
    
    .value {
        font-size: 28px;
        font-weight: bold;
        color: #007bff;
    }
    
    .unit {
        font-size: 12px;
        color: #666;
    }
</style>

Dynamic Annotations

Update annotation content based on gauge state or external data.

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge EnablePointerDrag="true">
    <CircularGaugeEvents OnDrag="@UpdateAnnotation">
    </CircularGaugeEvents>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="@currentValue">
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="30%" ZIndex="1">
                    <ContentTemplate>
                        <div class="dynamic-annotation">
                            <div class="label">Current Value</div>
                            <div class="value">@currentValue.ToString("F1")</div>
                            <div class="status">@GetStatus(currentValue)</div>
                        </div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    private double currentValue = 50;
    
    void UpdateAnnotation(Syncfusion.Blazor.CircularGauge.PointerDragEventArgs args)
    {
        currentValue = args.CurrentValue;
    }
    
    string GetStatus(double value)
    {
        if (value < 30) return "Low";
        if (value < 70) return "Normal";
        return "High";
    }
}

<style>
    .dynamic-annotation {
        text-align: center;
        padding: 10px;
        background: #f8f9fa;
        border-radius: 8px;
    }
    
    .label {
        font-size: 10px;
        color: #666;
        margin-bottom: 5px;
    }
    
    .value {
        font-size: 24px;
        font-weight: bold;
        color: #007bff;
        margin-bottom: 5px;
    }
    
    .status {
        font-size: 12px;
        color: #28a745;
    }
</style>

Use Cases

Value Display

Show the current pointer value with units and formatting at the gauge center.

Status Indicators

Display textual status (Normal, Warning, Critical) based on gauge values.

Legends and Labels

Add descriptive labels for ranges, zones, or specific values around the gauge.

Branding

Include company logos, product names, or branding elements.

Instructions

Provide usage instructions or guidance text for interactive gauges.

Multi-Metric Display

Show related metrics or calculated values derived from the main gauge reading.

Icon Indicators

Use icon fonts or images to represent states or categories visually.

Thresholds

Mark specific threshold values with annotations for quick reference.

Best Practices

1. Content Strategy

• Keep annotation text concise and readable
• Use appropriate font sizes for the gauge dimensions
• Ensure text contrasts well with backgrounds

2. Positioning

• Place important annotations where they won't obscure pointers
• Use consistent positioning patterns for similar annotations
• Consider gauge rotation and start/end angles

3. Z-Index Management

• Use lower Z-index values for background elements
• Use higher Z-index values for interactive or important content
• Test layering with different gauge configurations

4. Responsive Design

• Use percentage-based sizing where possible
• Test annotations at different gauge sizes
• Consider using media queries for complex layouts

5. Performance

• Minimize complex HTML in ContentTemplate
• Avoid heavy images or animations
• Limit the number of annotations for optimal rendering

6. Accessibility

• Provide meaningful text content
• Use semantic HTML elements
• Ensure sufficient color contrast
• Consider screen reader compatibility

Troubleshooting

Annotation Not Visible

Problem: Annotation is defined but not appearing.

Solutions:

• Verify the annotation is within the gauge boundaries
• Check Radius value places it in a visible location
• Ensure ZIndex is appropriate (not hidden behind other elements)
• Verify ContentTemplate or Content has visible content
• Check for CSS that might hide the annotation

Positioning Issues

Problem: Annotation appears in the wrong location.

Solutions:

• Verify Angle is in degrees (0-360)
• Check Radius is in correct format (percentage with % or pixels with px)
• Consider gauge's CenterX and CenterY if customized
• Account for axis StartAngle and EndAngle settings
• Review gauge dimensions and container sizing

Text Truncation

Problem: Annotation text is cut off or truncated.

Solutions:

• Increase container size in ContentTemplate
• Adjust Radius to provide more space
• Use smaller font sizes or abbreviations
• Apply CSS white-space and overflow properties appropriately
• Consider word-wrap or line-break CSS properties

Overlapping Content

Problem: Annotations overlap each other or gauge elements.

Solutions:

• Adjust Angle values to increase separation
• Modify Radius to create spacing
• Use different ZIndex values for proper layering
• Reduce annotation sizes or font sizes
• Consider repositioning or combining annotations

Dynamic Content Not Updating

Problem: Annotation content doesn't refresh when data changes.

Solutions:

• Ensure StateHasChanged() is called after data updates
• Verify binding syntax is correct in ContentTemplate
• Check that the component properly re-renders
• Use @key directive if rendering multiple similar annotations
• Verify event handlers are properly triggering updates

Styling Not Applied

Problem: CSS styles not affecting annotation appearance.

Solutions:

• Check CSS specificity and selector correctness
• Verify styles are defined within <style> tags in the component
• Use browser developer tools to inspect applied styles
• Ensure ContentTemplate div has appropriate class names
• Check for conflicting global styles
• Consider using inline styles for guaranteed application

Poor Performance with Many Annotations

Problem: Gauge renders slowly with multiple annotations.

Solutions:

• Reduce the number of annotations
• Simplify HTML content in ContentTemplate
• Optimize or compress images
• Remove unnecessary styling or animations
• Consider server-side rendering for initial load
• Use simpler text annotations instead of complex HTML when possible

CircularGauge API Reference (summary)

This file summarizes the primary API surface for SfCircularGauge and related child tags. Use this as a quick checklist when validating reference docs.

Table of Contents

• Namespace / Import
• Component: SfCircularGauge
• Core Properties
• Important Methods
• Events (common)
• Child Tags and Key Properties
• Styling CSS classes
• Typical Usage Snippet
• Notes for reference authors

Namespace / Import

• @using Syncfusion.Blazor.CircularGauge

Component: SfCircularGauge

Core Properties

• AllowImageExport (bool)
• AllowMargin (bool)
• AllowPdfExport (bool)
• AllowPrint (bool)
• AnimationDuration (double)
• Background (string)
• CenterX (string)
• CenterY (string)
• Description (string)
• EnableGroupingSeparator (bool)
• EnablePointerDrag (bool)
• EnableRangeDrag (bool)
• Height (string)
• ID (string)
• MoveToCenter (bool)
• TabIndex (int)
• Theme (enum)
• Title (string)
• Width (string)

Important Methods

• Task<string> ExportAsync(ExportType type, string fileName, PdfPageOrientation? orientation = null, bool allowDownload = true)
• Task PrintAsync()
• Task RefreshAsync()
• Task SetAnnotationValueAsync(int axisIndex, int annotationIndex, string content)
• Task SetPointerValueAsync(int axisIndex, int pointerIndex, double pointerValue)
• void SetRangeValue(int axisIndex, int rangeIndex, double start, double end)
• void UpdateChildProperties(string key, object keyValue)

Events (common)

• AnimationCompleted (AnimationCompleteEventArgs)
• AnnotationRendering (AnnotationRenderEventArgs)
• AxisLabelRendering (AxisLabelRenderEventArgs)
• Loaded / OnLoad (LoadedEventArgs)
• OnGaugeMouseDown / OnGaugeMouseMove / OnGaugeMouseUp / OnGaugeMouseLeave (MouseEventArgs)
• OnDrag, OnDragStart, OnDragEnd (PointerDragEventArgs)
• OnPrint (PrintEventArgs)
• OnRadiusCalculate (RadiusCalculateEventArgs)
• Resizing (ResizeEventArgs)
• TooltipRendering (TooltipRenderEventArgs)

Child Tags and Key Properties

• CircularGaugeAnnotation — Content, Angle, Radius, AutoAngle
• CircularGaugeAxes — collection of CircularGaugeAxis
• CircularGaugeAxis — Background, Direction, EndAngle, StartAngle, Maximum, Minimum, Radius
• CircularGaugeBorder — Color, Width
• CircularGaugeLegendSettings — Visible, Position, Shape, ToggleVisibility
• CircularGaugeMargin — Top, Bottom, Left, Right
• CircularGaugePointer — Type, Value, Color, MarkerShape, Position, PointerWidth, Radius
• CircularGaugeRange — Start, End, Color, StartWidth, EndWidth, Radius
• CircularGaugeTooltipSettings — Enable, Fill, Format, ShowAtMousePosition

Styling CSS classes

• e-circulargauge
• e-gauge-axis
• e-gauge-pointer
• e-gauge-range
• e-gauge-annotation

Typical Usage Snippet

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge Title="Basic Circular Gauge" Height="400px" Width="400px">
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100" StartAngle="200" EndAngle="160">
            <CircularGaugePointers>
                <CircularGaugePointer Value="65" Color="#007DD1" PointerWidth="8">
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="50" Color="#3A5998" StartWidth="10" EndWidth="10" />
                <CircularGaugeRange Start="50" End="100" Color="#33BCDA" StartWidth="10" EndWidth="10" />
            </CircularGaugeRanges>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Notes for reference authors

• Ensure each feature reference (pointers, ranges, annotations, axes, legend, appearance, user-interaction) includes related API property names and relevant events/methods.
• Link examples to this api-reference.md for consistent API terminology.
• Verify method signatures (async return types) against the official Syncfusion docs when adding code samples.

Appearance and Styling

Table of Contents

• Overview
• Themes
• Dimensions
• Title
• Center Positioning
• Background and Border
• Animation
• Print and Export

Overview

The CircularGauge component provides extensive styling options including built-in themes, custom dimensions, titles, positioning, animations, and export capabilities.

Themes

Syncfusion Blazor components come with built-in themes that can be applied by referencing the appropriate CSS file. The theme styling is controlled by CSS file references in the HTML head.

Available Themes

Reference themes in ~/index.html or App.razor:

<!-- Bootstrap 5 (default) -->
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

<!-- Material -->
<link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" />

<!-- Fabric (Office 365) -->
<link href="_content/Syncfusion.Blazor.Themes/fabric.css" rel="stylesheet" />

<!-- Fluent -->
<link href="_content/Syncfusion.Blazor.Themes/fluent.css" rel="stylesheet" />

<!-- Tailwind -->
<link href="_content/Syncfusion.Blazor.Themes/tailwind.css" rel="stylesheet" />

<!-- Bootstrap 4 -->
<link href="_content/Syncfusion.Blazor.Themes/bootstrap4.css" rel="stylesheet" />

<!-- High Contrast -->
<link href="_content/Syncfusion.Blazor.Themes/highcontrast.css" rel="stylesheet" />

Dark Themes

<!-- Material Dark -->
<link href="_content/Syncfusion.Blazor.Themes/material-dark.css" rel="stylesheet" />

<!-- Bootstrap 5 Dark -->
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5-dark.css" rel="stylesheet" />

<!-- Tailwind Dark -->
<link href="_content/Syncfusion.Blazor.Themes/tailwind-dark.css" rel="stylesheet" />

<!-- Fluent Dark -->
<link href="_content/Syncfusion.Blazor.Themes/fluent-dark.css" rel="stylesheet" />

<!-- Fabric Dark -->
<link href="_content/Syncfusion.Blazor.Themes/fabric-dark.css" rel="stylesheet" />

Custom Colors

Override default colors using custom CSS:

<style>
    .e-circulargauge .e-axis-line {
        stroke: #007DD1;
    }
    
    .e-circulargauge .e-pointer {
        fill: #E74C3C;
    }
</style>

Dimensions

Control the gauge size using the Width and Height properties to define custom dimensions for the circular gauge.

Fixed Dimensions (Pixels)

<SfCircularGauge Width="400px" Height="400px">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Use Cases:

• Fixed-size dashboard widgets
• Consistent sizing across pages
• Non-responsive layouts

Responsive Dimensions (Percentage)

<div style="width:800px; height:600px">
    <SfCircularGauge Width="100%" Height="100%">
        <CircularGaugeAxes>
            <CircularGaugeAxis>
                <CircularGaugePointers>
                    <CircularGaugePointer Value="65">
                    </CircularGaugePointer>
                </CircularGaugePointers>
            </CircularGaugeAxis>
        </CircularGaugeAxes>
    </SfCircularGauge>
</div>

Percentage Behavior:

• 100%: Fills the entire container
• 50%: Half of the container size
• Adapts to container resizing

Use Cases:

• Responsive dashboards
• Mobile-friendly applications
• Flexible layouts

Default Size

If no size is specified:

• Height: 450px
• Width: 100% (fills container width)

Aspect Ratio Consideration

For circular gauges, keep width and height equal or similar:

<!-- Square (ideal for full circles) -->
<SfCircularGauge Width="400px" Height="400px">
</SfCircularGauge>

<!-- Wide (good for semi-circles) -->
<SfCircularGauge Width="600px" Height="300px">
</SfCircularGauge>

Title

Add a descriptive title using the Title property and customize it with the CircularGaugeTitleStyle component to provide context for the gauge.

Basic Title

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Title="Speedometer">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Title Styling

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Title="Temperature Monitor">
    <CircularGaugeTitleStyle 
        Color="#007DD1" 
        FontWeight="bold" 
        Size="24px"
        FontFamily="Arial"
        FontStyle="normal">
    </CircularGaugeTitleStyle>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Title Style Properties:

• Color: Text color
• Size: Font size (e.g., "20px", "24px")
• FontWeight: normal, bold, lighter, bolder
• FontFamily: Font name
• FontStyle: normal, italic, oblique

Title with Subtitle

Use annotations for subtitles:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Title="CPU Usage">
    <CircularGaugeTitleStyle Color="#333" FontWeight="bold" Size="22px">
    </CircularGaugeTitleStyle>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAnnotations>
                <CircularGaugeAnnotation Angle="180" Radius="15%" ZIndex="1">
                    <ContentTemplate>
                        <div style="color:#666; font-size:14px;">Real-time Monitoring</div>
                    </ContentTemplate>
                </CircularGaugeAnnotation>
            </CircularGaugeAnnotations>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Center Positioning

Position the gauge anywhere in the container using the CenterX and CenterY properties to control the horizontal and vertical positioning of the gauge center.

Default Position (Center)

<!-- Default: CenterX="50%", CenterY="50%" -->
<SfCircularGauge>
</SfCircularGauge>

Position in Pixels

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge CenterX="100px" CenterY="100px">
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="90" EndAngle="180">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Use Case: Absolute positioning for specific layouts.

Position in Percentage

@using Syncfusion.Blazor.CircularGauge
<!-- Top-left corner -->
<SfCircularGauge CenterX="25%" CenterY="25%">
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="0" EndAngle="180">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<!-- Bottom-right area -->
<SfCircularGauge CenterX="75%" CenterY="75%">
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="180" EndAngle="360">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Percentage Reference:

• 0%, 0%: Top-left
• 50%, 50%: Center (default)
• 100%, 100%: Bottom-right

Use Cases:

• Multi-gauge dashboards
• Semi-circle gauges positioned strategically
• Asymmetric layouts

Background and Border

Customize the gauge's background using the Background property and border using the CircularGaugeBorder component with Color and Width properties.

Background Color

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Background="#F5F5F5">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Background Options:

• Solid colors: "#FFFFFF", "lightblue"
• Transparent: "transparent"
• RGB/RGBA: "rgba(0, 123, 255, 0.1)"

Border Styling

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Background="white">
    <CircularGaugeBorder Color="#007DD1" Width="3">
    </CircularGaugeBorder>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Border Properties:

• Color: Border color
• Width: Border thickness in pixels

Card-Style Gauge

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Background="white">
    <CircularGaugeBorder Color="#E0E0E0" Width="1">
    </CircularGaugeBorder>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="75">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

<style>
    .e-circulargauge {
        box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        border-radius: 8px;
    }
</style>

Animation

Animate all gauge elements on load using the AnimationDuration property and control pointer-specific animation with the CircularGaugePointerAnimation component using Enable and Duration properties.

Enabling Animation

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge AnimationDuration="2000">
    <CircularGaugeAxes>
        <CircularGaugeAxis Radius="80%" StartAngle="230" EndAngle="130">
            <CircularGaugePointers>
                <CircularGaugePointer Value="60" Radius="60%">
                    <CircularGaugePointerAnimation Enable="true" Duration="1500">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="30" Color="#30B32D">
                </CircularGaugeRange>
                <CircularGaugeRange Start="30" End="60" Color="#E0E0E0">
                </CircularGaugeRange>
            </CircularGaugeRanges>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

AnimationDuration Property:

• Value in milliseconds
• 0: No animation (default)
• 1000-3000: Typical duration
• Animates: Axis, ticks, labels, ranges, pointers, annotations

Animation Sequence: 1. Axis line draws 2. Ticks and labels appear 3. Ranges fill in 4. Pointers move to value 5. Annotations fade in

Pointer-Only Animation

For animated pointers without animating other elements:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="70">
                    <CircularGaugePointerAnimation Enable="true" Duration="1500">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Disabling Animation

<!-- No gauge animation -->
<SfCircularGauge AnimationDuration="0">
</SfCircularGauge>

<!-- No pointer animation -->
<CircularGaugePointerAnimation Enable="false">
</CircularGaugePointerAnimation>

When to Disable:

• Real-time data updates
• Performance concerns
• User interactions (dragging)

Print and Export

Export gauges as images or PDF, or print directly using the AllowPrint, AllowImageExport, and AllowPdfExport properties to enable export functionality and call corresponding export methods.

Print

@using Syncfusion.Blazor.CircularGauge

<button @onclick="PrintGauge">Print Gauge</button>

<SfCircularGauge @ref="Gauge" AllowPrint="true">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    SfCircularGauge Gauge;
    
    void PrintGauge()
    {
        this.Gauge.PrintAsync();
    }
}

Requirements:

• Set AllowPrint="true"
• Call Print() method
• Opens browser print dialog

Export as Image

@using Syncfusion.Blazor.CircularGauge

<button @onclick="ExportPNG">Export PNG</button>
<button @onclick="ExportJPEG">Export JPEG</button>
<button @onclick="ExportSVG">Export SVG</button>

<SfCircularGauge @ref="Gauge" AllowImageExport="true">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="75">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    SfCircularGauge Gauge;
    
    void ExportPNG()
    {
        Gauge.ExportAsync(Syncfusion.Blazor.CircularGauge.ExportType.PNG, "CircularGauge");
    }
    
    void ExportJPEG()
    {
        Gauge.ExportAsync(Syncfusion.Blazor.CircularGauge.ExportType.JPEG, "CircularGauge");
    }
    
    void ExportSVG()
    {
        Gauge.ExportAsync(Syncfusion.Blazor.CircularGauge.ExportType.SVG, "CircularGauge");
    }
}

Image Export Formats:

• ExportType.PNG: Best for web, supports transparency
• ExportType.JPEG: Smaller file size, no transparency
• ExportType.SVG: Vector format, scalable

Requirements:

• Set AllowImageExport="true"
• Call Export(type, filename)

Export as PDF

@using Syncfusion.Blazor.CircularGauge

<button @onclick="ExportPDFPortrait">Export PDF (Portrait)</button>
<button @onclick="ExportPDFLandscape">Export PDF (Landscape)</button>

<SfCircularGauge @ref="Gauge" AllowPdfExport="true">
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="80">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

@code {
    SfCircularGauge Gauge;
    
    void ExportPDFPortrait()
    {
        Gauge.ExportAsync(Syncfusion.Blazor.CircularGauge.ExportType.PDF, "CircularGauge");
    }
    
    void ExportPDFLandscape()
    {
        Gauge.ExportAsync(Syncfusion.Blazor.CircularGauge.ExportType.PDF, "CircularGauge");
    }
}

PDF Orientation:

• 0: Portrait
• 1: Landscape

Requirements:

• Set AllowPdfExport="true"
• Call Export(ExportType.PDF, filename, orientation)

Export Use Cases

1. Reports: Export gauges for PDF reports 2. Documentation: Save gauge screenshots 3. Sharing: Share gauge images via email/messaging 4. Archiving: Store historical gauge states 5. Presentations: Include gauge images in slides

Best Practices

Themes

• Use consistent themes across your application
• Test with both light and dark themes
• Consider accessibility with high-contrast themes

Dimensions

• Use percentage for responsive layouts
• Use pixels for fixed dashboards
• Maintain aspect ratio for circular gauges

Titles

• Keep titles concise (2-4 words)
• Use descriptive, meaningful titles
• Style consistently with your brand

Positioning

• Center by default for best visual balance
• Adjust only for specific layout needs
• Test positioning across screen sizes

Background

• Use subtle backgrounds (light grays, whites)
• Avoid busy patterns that distract
• Ensure contrast with gauge elements

Animation

• Enable on initial load for polish
• Disable for real-time updates
• Use moderate durations (1-2 seconds)

Export

• Name exports descriptively
• Choose format based on use case
• Test export quality before production

Troubleshooting

Gauge appears cut off:

• Increase container size
• Reduce axis radius percentage
• Adjust CenterX/CenterY positioning

Theme not applying:

• Verify CSS file reference in index.html
• Check file path is correct
• Clear browser cache

Animation stuttering:

• Reduce AnimationDuration
• Disable for performance-sensitive scenarios
• Check for other performance bottlenecks

Export not working:

• Verify AllowImageExport or AllowPdfExport is true
• Check browser console for errors
• Test with a simple gauge first

Title overlaps gauge:

• Reduce title font size
• Increase gauge height
• Adjust title positioning with CSS

Responsive sizing issues:

• Ensure parent container has explicit dimensions
• Use percentage for Width/Height
• Test across different screen sizes

Axes Configuration

Table of Contents

• Overview
• Axis Customization
• Minimum and Maximum
• Start and End Angles
• Axis Radius
• Ticks Configuration
• Labels Configuration
• Axis Direction
• Multiple Axes
• Common Use Cases

Overview

By default, the Circular Gauge displays with an axis. Each axis can contain its own ranges, pointers, and annotations. Understanding axis configuration is essential for creating effective circular gauge visualizations.

Key Capabilities:

• Customize axis appearance (line width, color, background)
• Set minimum and maximum scale values
• Configure start/end angles for custom arc shapes
• Control axis radius in pixels or percentage
• Configure major and minor ticks
• Customize axis labels (format, position, styling)
• Set axis direction (clockwise/anticlockwise)
• Implement multiple axes on a single gauge

Axis Customization

Basic Axis Styling

Customize the axis line width and color using CircularGaugeAxisLineStyle, and set the axis background using the Background property:

@using Syncfusion.Blazor.CircularGauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Background="rgba(0, 128, 128, 0.3)">
            <CircularGaugeAxisLineStyle Width="2" Color="red">
            </CircularGaugeAxisLineStyle>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Properties:

• Width: Axis line width (default: 2)
• Color: Axis line color (e.g., "red", "#FF0000", "rgb(255,0,0)")
• Background: Axis background color (supports rgba for transparency)

Use Case: Highlight the axis with colored backgrounds for visual emphasis or brand consistency.

Minimum and Maximum

Define the scale range using Minimum and Maximum properties:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="50" Maximum="250">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Default Values:

• Minimum: 0
• Maximum: 100

Examples:

• Temperature gauge: Minimum="-20", Maximum="50"
• Speedometer: Minimum="0", Maximum="200"
• Percentage gauge: Minimum="0", Maximum="100"
• Pressure gauge: Minimum="0", Maximum="3000"

Important: Pointer values and range values must fall within the minimum-maximum range.

Start and End Angles

Control the sweep angle of the gauge using StartAngle and EndAngle properties. The gauge can sweep from 0 to 360 degrees.

Default Angles

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <!-- Default: StartAngle=200, EndAngle=160 -->
        <CircularGaugeAxis>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Custom Angles

Semi-Circle Gauge (Bottom Half)

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="270" EndAngle="90">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Semi-Circle Gauge (Top Half)

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="90" EndAngle="270">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Quarter-Circle Gauge

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="180" EndAngle="270">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Full-Circle Gauge

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="0" EndAngle="360">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Speedometer-Style Gauge

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis StartAngle="220" EndAngle="140">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Angle Reference:

• 0° = 3 o'clock position (right)
• 90° = 6 o'clock position (bottom)
• 180° = 9 o'clock position (left)
• 270° = 12 o'clock position (top)

Use Cases:

• Speedometer: 220° to 140° (classic car dashboard look)
• Temperature indicator: 270° to 90° (bottom semi-circle)
• Progress indicator: 0° to 360° (full circle)
• Battery level: 180° to 0° (right quarter-circle)

Axis Radius

Control the size of the axis using the Radius property. The radius can be specified in pixels or percentage.

Radius in Pixels

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Radius="150px">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

When to use pixels:

• Fixed-size gauges that don't need to scale
• Precise control over gauge dimensions
• Non-responsive layouts

Radius in Percentage

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Radius="50%">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Percentage Behavior:

• Percentage is calculated relative to the gauge's available size
• "50%" renders the gauge at half the available space
• "80%" is a common value for good spacing
• "100%" fills the entire available area

When to use percentage:

• Responsive designs that adapt to container size
• Dashboards with dynamic layouts
• Mobile-friendly applications

Default: Auto-calculated based on available size

Example: Multiple Axes with Different Radii

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Radius="80%">
            <!-- Outer axis -->
        </CircularGaugeAxis>
        <CircularGaugeAxis Radius="50%">
            <!-- Inner axis -->
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Ticks Configuration

Ticks are the small lines on the axis that mark scale divisions. There are two types: major ticks and minor ticks.

Major Ticks

Major ticks mark significant scale divisions:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisMajorTicks 
                Interval="10" 
                Color="red" 
                Height="10" 
                Width="3">
            </CircularGaugeAxisMajorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Properties:

• Interval: Value interval between ticks (default: auto-calculated)
• Height: Tick length in pixels
• Width: Tick thickness in pixels
• Color: Tick color
• Position: Inside, Outside, or Cross (default: Inside)
• Offset: Distance from axis line

Minor Ticks

Minor ticks provide finer scale divisions between major ticks:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisMinorTicks 
                Interval="5" 
                Color="green" 
                Height="5" 
                Width="2">
            </CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Complete Tick Configuration Example

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugeAxisMajorTicks 
                Interval="10" 
                Color="#333" 
                Height="12" 
                Width="2"
                Position="Position.Inside">
            </CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks 
                Interval="2" 
                Color="#999" 
                Height="6" 
                Width="1"
                Position="Position.Inside">
            </CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Tick Positioning

Control tick placement using Offset and Position properties:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisMajorTicks 
                Position="Syncfusion.Blazor.CircularGauge.Position.Outside" 
                Offset="5"
                Height="10">
            </CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks 
                Position="Syncfusion.Blazor.CircularGauge.Position.Outside" 
                Offset="5"
                Height="5">
            </CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Position Options:

• Position.Inside: Ticks point inward (default)
• Position.Outside: Ticks point outward
• Position.Cross: Ticks cross the axis line

Offset:

• Positive values move ticks away from the axis
• Negative values move ticks toward the axis center
• Default: 0

Hiding Ticks

To hide ticks, set Height="0":

<CircularGaugeAxisMajorTicks Height="0"></CircularGaugeAxisMajorTicks>
<CircularGaugeAxisMinorTicks Height="0"></CircularGaugeAxisMinorTicks>

Labels Configuration

Axis labels display the scale values. Customize them using CircularGaugeAxisLabelStyle.

Basic Label Styling

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisLabelStyle>
                <CircularGaugeAxisLabelFont 
                    Color="red" 
                    Size="20px" 
                    FontWeight="Bold"
                    FontFamily="Arial">
                </CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Font Properties:

• Color: Label text color
• Size: Font size (e.g., "12px", "16px")
• FontWeight: Normal, Bold, Lighter, Bolder
• FontFamily: Font name (e.g., "Arial", "Segoe UI")
• FontStyle: Normal, Italic, Oblique

Label Positioning

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisLabelStyle 
                Position="Syncfusion.Blazor.CircularGauge.Position.Outside" 
                Offset="10">
            </CircularGaugeAxisLabelStyle>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Position Options:

• Position.Inside: Labels inside the axis (default)
• Position.Outside: Labels outside the axis
• Position.Cross: Labels on the axis line

Offset: Distance from ticks (default: 0)

Auto-Angle Labels

Make labels follow the axis curve:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugeAxisLabelStyle AutoAngle="true">
            </CircularGaugeAxisLabelStyle>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

When to use: Improves readability on gauges with non-standard angles or full circles.

Label Formatting

Standard Format

Format labels using globalize patterns:

<CircularGaugeAxisLabelStyle Format="n2"></CircularGaugeAxisLabelStyle>

Common Formats:

Custom Format with Units

<CircularGaugeAxisLabelStyle Format="{value}°C"></CircularGaugeAxisLabelStyle>

Examples:

• "{value}°C" → Temperature (20°C)
• "{value} km/h" → Speed (65 km/h)
• "{value} PSI" → Pressure (30 PSI)
• "{value}%" → Percentage (75%)
• "${value}" → Currency ($1000)

Smart Labels (Hiding Overlapping Labels)

When the axis forms a complete circle (0°-360°), the first and last labels overlap. Hide one using HiddenLabel:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis 
            Minimum="0" 
            Maximum="12" 
            StartAngle="0" 
            EndAngle="360">
            <CircularGaugeAxisLabelStyle HiddenLabel="HiddenLabel.First">
            </CircularGaugeAxisLabelStyle>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Options:

• HiddenLabel.First: Hide the first label
• HiddenLabel.Last: Hide the last label
• HiddenLabel.None: Show all labels (default)

Show Last Label

If the maximum value doesn't align with the tick interval, the last label is hidden by default. Force it to display:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Maximum="100" ShowLastLabel="true">
            <CircularGaugeAxisMajorTicks Interval="30"></CircularGaugeAxisMajorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Example: With Maximum="100" and Interval="30", labels appear at 0, 30, 60, 90. Setting ShowLastLabel="true" also shows 100.

Hide Intersecting Labels

Automatically hide labels that overlap each other:

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis 
            Maximum="200" 
            StartAngle="270" 
            EndAngle="90" 
            HideIntersectingLabel="true">
            <CircularGaugeAxisMajorTicks Interval="4"></CircularGaugeAxisMajorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Use Case: Prevents label clutter on gauges with many ticks or custom angles.

Hiding Labels Completely

<CircularGaugeAxisLabelStyle>
    <CircularGaugeAxisLabelFont Size="0px"></CircularGaugeAxisLabelFont>
</CircularGaugeAxisLabelStyle>

Axis Direction

Control whether the gauge progresses clockwise or counter-clockwise:

Clockwise (Default)

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Direction="GaugeDirection.ClockWise">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

AntiClockwise

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Direction="GaugeDirection.AntiClockWise">
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Use Cases:

• Countdown timers: Use AntiClockWise for visual countdown effect
• Reverse indicators: Show decreasing values
• Cultural preferences: Some regions prefer counter-clockwise progression

Multiple Axes

Add multiple axes to display different scales or measurement systems on a single gauge:

<SfCircularGauge>
    <CircularGaugeAxes>
        <!-- First Axis: Speed in km/h -->
        <CircularGaugeAxis Minimum="0" Maximum="140" Radius="80%">
            <CircularGaugeAxisLabelStyle>
                <CircularGaugeAxisLabelFont Size="12px"></CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugePointers>
                <CircularGaugePointer Value="80" Type="PointerType.Needle">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
        
        <!-- Second Axis: Temperature in °C -->
        <CircularGaugeAxis Minimum="-20" Maximum="60" Radius="50%">
            <CircularGaugeAxisLabelStyle Position="Syncfusion.Blazor.CircularGauge.Position.Outside">
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisMajorTicks Position="Syncfusion.Blazor.CircularGauge.Position.Outside">
            </CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks Position="Syncfusion.Blazor.CircularGauge.Position.Outside">
            </CircularGaugeAxisMinorTicks>
            <CircularGaugePointers>
                <CircularGaugePointer 
                    Value="22" 
                    Type="PointerType.Marker" 
                    MarkerShape="GaugeShape.InvertedTriangle"
                    MarkerHeight="20"
                    MarkerWidth="20">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Design Tips:

• Use different radii to nest axes (outer and inner)
• Position labels and ticks differently (inside vs outside) to avoid overlap
• Use different pointer types for visual distinction
• Assign different colors to each axis's elements

Use Cases:

• Dual measurement: Speed (km/h) and fuel level on the same gauge
• Temperature and humidity: Two environmental metrics
• Currency conversion: Same value in two currencies
• RPM and speed: Engine RPM and vehicle speed

Common Use Cases

Clock-Style Gauge (12-Hour)

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis 
            Minimum="0" 
            Maximum="12" 
            StartAngle="0" 
            EndAngle="360">
            <CircularGaugeAxisLabelStyle HiddenLabel="HiddenLabel.First">
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisMajorTicks Interval="1" Height="10">
            </CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks Interval="0.2" Height="5">
            </CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Temperature Gauge with Custom Labels

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="-30" Maximum="50" StartAngle="270" EndAngle="90">
            <CircularGaugeAxisLabelStyle Format="{value}°C" Position="Position.Outside">
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisMajorTicks Interval="10" Position="Position.Outside">
            </CircularGaugeAxisMajorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Percentage Gauge with Clean Design

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugeAxisLabelStyle Format="{value}%">
                <CircularGaugeAxisLabelFont Size="14px" FontWeight="Bold">
                </CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisLineStyle Width="0"></CircularGaugeAxisLineStyle>
            <CircularGaugeAxisMajorTicks Height="0"></CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks Height="0"></CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Speedometer with Outside Labels

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis 
            Minimum="0" 
            Maximum="200" 
            StartAngle="220" 
            EndAngle="140">
            <CircularGaugeAxisLabelStyle 
                Position="Syncfusion.Blazor.CircularGauge.Position.Outside" 
                AutoAngle="true">
                <CircularGaugeAxisLabelFont Size="12px" Color="#333">
                </CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisLineStyle Width="8" Color="#E0E0E0">
            </CircularGaugeAxisLineStyle>
            <CircularGaugeAxisMajorTicks 
                Interval="20" 
                Height="12" 
                Width="2" 
                Color="#666">
            </CircularGaugeAxisMajorTicks>
            <CircularGaugeAxisMinorTicks 
                Interval="5" 
                Height="6" 
                Width="1" 
                Color="#999">
            </CircularGaugeAxisMinorTicks>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Best Practices

1. Choose appropriate min/max values: Match the scale to your data range 2. Use readable label formats: Add units for clarity (°C, km/h, %) 3. Balance tick density: Too many ticks clutter; too few lack precision 4. Position labels strategically: Use Outside for prominence, Inside for compactness 5. Handle overlapping labels: Use HiddenLabel, HideIntersectingLabel, or ShowLastLabel 6. Match angles to use case: Semi-circle for speedometers, full circle for clocks 7. Use percentage radius for responsiveness: Makes gauges adapt to container size 8. Multiple axes need visual separation: Use different radii and positions 9. Consider axis direction: Clockwise feels natural for most Western audiences 10. Test readability: Ensure labels and ticks are visible at various sizes

Troubleshooting

Issue: Labels are cut off

• Solution: Increase gauge dimensions or reduce font size, or use Position.Inside

Issue: First and last labels overlap

• Solution: Use HiddenLabel="HiddenLabel.First" or HiddenLabel.Last"

Issue: Last label doesn't appear

• Solution: Set ShowLastLabel="true" on the axis

Issue: Ticks are too dense

• Solution: Increase Interval values for major/minor ticks

Issue: Axis doesn't fill the gauge

• Solution: Increase Radius percentage (try "90%" or "95%")

Issue: Multiple axes overlap

• Solution: Use different Radius values (e.g., 80% for outer, 50% for inner)

Issue: Custom format not applying

• Solution: Ensure Format string uses {value} placeholder correctly

Getting Started with Blazor CircularGauge

This guide explains how to set up and create your first Syncfusion Blazor CircularGauge component in a Blazor WebAssembly application.

Table of Contents

• Prerequisites
• Installation Steps
• Option 1: Visual Studio
• Option 2: Visual Studio Code
• Option 3: .NET CLI
• Configuration Steps
• Step 1: Add Import Namespaces
• Step 2: Register Syncfusion Blazor Service
• Step 3: Add Stylesheet and Script Resources
• Creating Your First CircularGauge
• Basic Gauge
• Set Pointer Value
• Adding a Title
• Adding Ranges
• Complete Example
• Project Structure
• Running the Application
• Common Issues and Troubleshooting
• Issue: Gauge Not Rendering
• Issue: Styles Not Applied
• Issue: Script Errors
• Issue: Component Namespace Not Found
• Next Steps
• Additional Resources
• Key Takeaways

Prerequisites

Before you begin, ensure you have:

• System Requirements: Compatible with the Blazor component system requirements
• Development Environment: Visual Studio, Visual Studio Code, or .NET CLI
• Blazor Knowledge: Basic understanding of Blazor applications

Installation Steps

Option 1: Visual Studio

Step 1: Create a Blazor WebAssembly App

1. Open Visual Studio 2. Create a Blazor WebAssembly App using Microsoft Templates or Syncfusion Blazor Extension 3. For detailed instructions, refer to Blazor WASM App Getting Started

Step 2: Install NuGet Packages

Via NuGet Package Manager UI: 1. Navigate to Tools → NuGet Package Manager → Manage NuGet Packages for Solution 2. Search and install:

• Syncfusion.Blazor.CircularGauge
• Syncfusion.Blazor.Themes

Via Package Manager Console:

Install-Package Syncfusion.Blazor.CircularGauge -Version 27.1.48
Install-Package Syncfusion.Blazor.Themes -Version 27.1.48

Note: Replace version numbers with the latest available version. Syncfusion Blazor components are available at nuget.org.

Option 2: Visual Studio Code

Step 1: Create a Blazor WebAssembly App

1. Open Visual Studio Code 2. Create via Syncfusion Blazor Extension or use the integrated terminal:

dotnet new blazorwasm -o BlazorApp
cd BlazorApp

Step 2: Install NuGet Packages

Open the integrated terminal (Ctrl + `) in the project root directory and run:

dotnet add package Syncfusion.Blazor.CircularGauge -v 27.1.48
dotnet add package Syncfusion.Blazor.Themes -v 27.1.48
dotnet restore

Option 3: .NET CLI

Step 1: Verify .NET SDK Installation

Check your .NET SDK version:

dotnet --version

Step 2: Create a Blazor WebAssembly App

dotnet new blazorwasm -o BlazorApp
cd BlazorApp

Step 3: Install NuGet Packages

dotnet add package Syncfusion.Blazor.CircularGauge -Version 27.1.48
dotnet add package Syncfusion.Blazor.Themes -Version 27.1.48
dotnet restore

Configuration Steps

Step 1: Add Import Namespaces

Open ~/_Imports.razor and add the following namespaces:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.CircularGauge

This makes the CircularGauge component available throughout your application.

Step 2: Register Syncfusion Blazor Service

Open ~/Program.cs and register the Syncfusion Blazor service:

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

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();

Step 3: Add Stylesheet and Script Resources

Add the theme stylesheet and script references in the <head> section of ~/index.html:

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>BlazorApp</title>
    <base href="/" />
    
    <!-- Syncfusion Blazor Theme -->
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    
    <!-- Syncfusion Blazor Script -->
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

Available Themes:

• bootstrap5.css (default)
• material.css
• fabric.css
• fluent.css
• bootstrap.css
• bootstrap4.css
• tailwind.css
• tailwind-dark.css
• material-dark.css
• bootstrap-dark.css
• bootstrap5-dark.css
• fluent-dark.css
• fabric-dark.css

Note: You can also reference themes via CDN or use the Custom Resource Generator (CRG). See Blazor Themes documentation for more options.

Creating Your First CircularGauge

Basic Gauge

Add the CircularGauge component in ~/Pages/Index.razor:

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

<h3>My First Circular Gauge</h3>

<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer></CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Run the Application:

• Windows: Press Ctrl + F5
• macOS: Press ⌘ + F5

This renders a basic circular gauge with default settings (scale 0-100, pointer at 0).

Set Pointer Value

Modify the pointer value using the Value property:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="35">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

The pointer now points to 35 on the scale.

Note: You can configure multiple axes in a CircularGauge, and each axis can have multiple pointers.

Adding a Title

Provide context to your gauge with a title:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge Title="Speedometer">
    <CircularGaugeTitleStyle Color="blue" FontWeight="bold" Size="25">
    </CircularGaugeTitleStyle>
    <CircularGaugeAxes>
        <CircularGaugeAxis>
            <CircularGaugePointers>
                <CircularGaugePointer Value="35">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Title Properties:

• Color: Title text color
• FontWeight: Font weight (normal, bold, etc.)
• Size: Font size (e.g., "25", "18px")
• FontFamily: Font family
• FontStyle: Font style (normal, italic)

Adding Ranges

Ranges help visualize different zones or thresholds on the gauge:

@using Syncfusion.Blazor.CircularGauge
<SfCircularGauge>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="100">
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="40" Color="#30B32D">
                </CircularGaugeRange>
                <CircularGaugeRange Start="40" End="80" Color="#FFDD00">
                </CircularGaugeRange>
                <CircularGaugeRange Start="80" End="100" Color="#F03E3E">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65">
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

This creates three color-coded zones:

• Green (0-40): Safe zone
• Yellow (40-80): Warning zone
• Red (80-100): Critical zone

Complete Example

Here's a complete example combining all the elements:

@page "/gauge-demo"
@using Syncfusion.Blazor.CircularGauge

<h3>Speed Monitor</h3>

<SfCircularGauge Title="Vehicle Speed" Width="400px" Height="400px">
    <CircularGaugeTitleStyle Color="#333" FontWeight="bold" Size="20">
    </CircularGaugeTitleStyle>
    <CircularGaugeAxes>
        <CircularGaugeAxis Minimum="0" Maximum="120" StartAngle="220" EndAngle="140">
            <CircularGaugeAxisLabelStyle>
                <CircularGaugeAxisLabelFont Size="12px"></CircularGaugeAxisLabelFont>
            </CircularGaugeAxisLabelStyle>
            <CircularGaugeAxisLineStyle Width="10" Color="#E0E0E0">
            </CircularGaugeAxisLineStyle>
            <CircularGaugeRanges>
                <CircularGaugeRange Start="0" End="40" Color="#30B32D">
                </CircularGaugeRange>
                <CircularGaugeRange Start="40" End="80" Color="#FFDD00">
                </CircularGaugeRange>
                <CircularGaugeRange Start="80" End="120" Color="#F03E3E">
                </CircularGaugeRange>
            </CircularGaugeRanges>
            <CircularGaugePointers>
                <CircularGaugePointer Value="65" Radius="60%" Color="#333">
                    <CircularGaugePointerAnimation Enable="true" Duration="1500">
                    </CircularGaugePointerAnimation>
                </CircularGaugePointer>
            </CircularGaugePointers>
        </CircularGaugeAxis>
    </CircularGaugeAxes>
</SfCircularGauge>

Project Structure

After setup, your project structure should look like this:

BlazorApp/
├── Pages/
│   ├── Index.razor          (Your gauge implementation)
│   └── ...
├── Shared/
│   └── ...
├── wwwroot/
│   └── index.html           (Theme and script references)
├── _Imports.razor           (Namespace imports)
├── Program.cs               (Service registration)
└── BlazorApp.csproj         (NuGet package references)

Running the Application

1. Build the Project: Ensure no compilation errors 2. Run: Press Ctrl + F5 (Windows) or ⌘ + F5 (macOS) 3. View: The gauge renders in your default browser

Common Issues and Troubleshooting

Issue: Gauge Not Rendering

Solution: 1. Verify NuGet packages are installed 2. Check that AddSyncfusionBlazor() is called in Program.cs 3. Ensure theme CSS and script are referenced in index.html 4. Confirm namespaces are imported in _Imports.razor

Issue: Styles Not Applied

Solution: 1. Check theme CSS path in index.html 2. Verify the CSS file is served correctly (check browser DevTools) 3. Try using CDN instead: https://cdn.syncfusion.com/blazor/{version}/styles/bootstrap5.css

Issue: Script Errors

Solution: 1. Ensure syncfusion-blazor.min.js is referenced after the closing </body> tag or in <head> 2. Verify script path is correct 3. Check browser console for specific error messages

Issue: Component Namespace Not Found

Solution: 1. Rebuild the project after installing NuGet packages 2. Restart Visual Studio/VS Code 3. Run dotnet restore in the terminal

Next Steps

Now that you have a basic CircularGauge running, explore these features:

1. Axes Configuration: Customize axis appearance, labels, ticks, and ranges 2. Pointer Types: Use needle, range bar, or marker pointers 3. Annotations: Add text, images, or custom HTML content 4. User Interaction: Enable tooltips and pointer dragging 5. Legends: Display legends for ranges 6. Animations: Configure smooth pointer animations 7. Themes: Apply different built-in themes or create custom styles 8. Events: Handle gauge events for interactivity 9. Real-Time Updates: Update pointer values dynamically 10. Accessibility: Ensure WCAG compliance for all users

Additional Resources

• GitHub Sample: View complete getting started sample
• Live Demos: Explore Blazor CircularGauge demos
• API Documentation: CircularGauge API reference
• Theme Documentation: Blazor Themes guide
• Server App Setup: For Blazor Server apps, see getting started with server app
• Web App Setup: For Blazor Web App (.NET 8+), see getting started with web app

Key Takeaways

• Three NuGet packages required: CircularGauge, Themes, and Core (dependency)
• Service registration is mandatory: Call AddSyncfusionBlazor() in Program.cs
• Theme CSS and script must be referenced: Add to index.html
• Basic structure: SfCircularGauge → CircularGaugeAxes → CircularGaugeAxis → CircularGaugePointers
• Ranges are optional but powerful: Use them to create visual zones
• Start simple, then enhance: Begin with a basic gauge, then add features incrementally