Skills
skills/syncfusion/winui-ui-components-skills/syncfusion-winui-linear-gauge

syncfusion-winui-linear-gauge

SKILL.md

WinUI Linear Gauge (SfLinearGauge)

Comprehensive guide for implementing the Syncfusion WinUI Linear Gauge (SfLinearGauge) control for data visualization in Windows desktop applications. The Linear Gauge control displays numerical values on a linear scale horizontally or vertically with extensive customization options, ranges, multiple pointer types, and animation support.

When to Use This Skill

Use this skill when you need to:

  • Create linear gauge controls for data visualization in WinUI desktop applications
  • Display numerical values on horizontal or vertical linear scales
  • Add range indicators to visualize value categories with color-coded segments
  • Use bar pointers to show current values with filled indicators
  • Use shape pointers to mark values with different shapes (circle, diamond, triangle, etc.)
  • Use content pointers to display custom content (text, images, icons) at values
  • Animate pointer movements with customizable duration and easing functions
  • Enable interactive gauges with draggable pointers for value input
  • Customize axis appearance with labels, ticks, intervals, and formatting
  • Build dashboards with temperature, pressure, speed, or other measurement displays
  • Create progress indicators with visual feedback and ranges
  • Troubleshoot gauge rendering, pointer positioning, or interaction issues

Component Overview

SfLinearGauge is a multipurpose data visualization control that displays numerical values on a linear scale, offering:

  • Orientation: Horizontal or vertical gauge layouts
  • Axis Customization: Configurable scale with labels, ticks, intervals, and custom ranges
  • Range Support: Multiple color-coded ranges to visualize value categories
  • Three Pointer Types:
    • Bar Pointer: Filled bar from start to value
    • Shape Pointer: Markers with built-in shapes or custom templates
    • Content Pointer: Custom content (text, images, icons) at value position
  • Multiple Pointers: Add multiple pointers to show different values on same scale
  • Animation: Smooth pointer transitions with customizable easing functions
  • Interactivity: Draggable shape pointers for user input
  • Customization: Extensive styling, templates, gradients, and child content support
  • Data Binding: MVVM-friendly with Value property binding

Control Structure:

  • Single axis with configurable minimum, maximum, and interval
  • Multiple ranges for color-coded value segments
  • Bar pointers collection for filled indicators
  • Marker pointers collection for shape and content pointers
  • Full control over appearance, positioning, and behavior

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

  • Creating a WinUI 3 desktop application
  • Installing Syncfusion.Gauge.WinUI NuGet package
  • Adding Linear Gauge control in XAML
  • Adding Linear Gauge control in C#
  • Adding axis to the gauge
  • Adding ranges for value visualization
  • Adding bar pointers
  • Adding marker pointers (shape and content)
  • Complete working example

Axis Customization

📄 Read: references/axis-customization.md

  • Setting minimum and maximum values
  • Configuring intervals between labels
  • Axis direction customization (IsInversed)
  • Mirrored axis support (IsMirrored)
  • Axis orientation (horizontal/vertical)
  • Maximum labels count per 100 pixels
  • Axis line styling (stroke, thickness, color)
  • Axis line visibility control
  • Label customization (fonts, colors, formats)
  • Label templates for custom appearance
  • Label visibility and placement (inside/outside)
  • Label position and offset adjustment
  • Tick customization (major and minor ticks)
  • Tick styling and dashed patterns
  • Tick placement and offset
  • Custom scale ranges (logarithmic, etc.)

Ranges

📄 Read: references/ranges.md

  • Setting start and end values for ranges
  • Range width customization (StartWidth, MidWidth, EndWidth)
  • Equal vs. different width ranges
  • Background color customization
  • Gradient brush support with multiple stops
  • Range position (inside/outside/cross axis)
  • Using range colors for axis elements
  • Range child content support for labels

Pointers

📄 Read: references/pointers.md

  • Overview of three pointer types
  • Bar Pointer implementation and customization
  • Shape Pointer with built-in and custom shapes
  • Content Pointer for text, images, and icons
  • Multiple pointers on single gauge
  • Pointer dragging and interactivity
  • Pointer events (ValueChangeStarted, ValueChanging, ValueChanged, ValueChangeCompleted)
  • Pointer positioning and anchoring
  • Pointer sizing and styling

Animation

📄 Read: references/animation.md

  • Enabling pointer animation
  • Animation duration configuration
  • Animation easing functions
  • Applying animation to bar pointers
  • Applying animation to marker pointers
  • Custom animation timing and effects

Quick Start Example

Here's a minimal working example to get started:

1. Add Namespace

XAML:

<Window xmlns:gauge="using:Syncfusion.UI.Xaml.Gauges">

C#:

using Syncfusion.UI.Xaml.Gauges;

2. Create Basic Linear Gauge (XAML)

<Window
    x:Class="GaugeApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:gauge="using:Syncfusion.UI.Xaml.Gauges">
    
    <Grid>
        <gauge:SfLinearGauge>
            <gauge:SfLinearGauge.Axis>
                <gauge:LinearAxis Minimum="0"
                                  Maximum="100"
                                  Interval="10">
                    <gauge:LinearAxis.BarPointers>
                        <gauge:BarPointer Value="60" />
                    </gauge:LinearAxis.BarPointers>
                </gauge:LinearAxis>
            </gauge:SfLinearGauge.Axis>
        </gauge:SfLinearGauge>
    </Grid>
</Window>

3. Or Create Programmatically (C#)

using Syncfusion.UI.Xaml.Gauges;

namespace GaugeApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create gauge programmatically
            SfLinearGauge sfLinearGauge = new SfLinearGauge();
            sfLinearGauge.Axis.Minimum = 0;
            sfLinearGauge.Axis.Maximum = 100;
            sfLinearGauge.Axis.Interval = 10;
            
            // Add bar pointer
            BarPointer barPointer = new BarPointer();
            barPointer.Value = 60;
            sfLinearGauge.Axis.BarPointers.Add(barPointer);
            
            this.Content = sfLinearGauge;
        }
    }
}

4. Set Pointer Value (Optional)

// Update pointer value
barPointer.Value = 75;

// With animation
barPointer.EnableAnimation = true;
barPointer.AnimationDuration = 1000; // 1 second
barPointer.Value = 90;

Common Patterns

Pattern 1: Basic Horizontal Gauge with Bar Pointer

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Minimum="0" Maximum="100" Interval="10">
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="60" Background="Green" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 2: Vertical Temperature Gauge

<gauge:SfLinearGauge Orientation="Vertical">
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Minimum="-60" Maximum="60" Interval="20">
            <gauge:LinearAxis.Ranges>
                <gauge:LinearGaugeRange StartValue="-60" EndValue="0" Background="Blue" />
                <gauge:LinearGaugeRange StartValue="0" EndValue="30" Background="Orange" />
                <gauge:LinearGaugeRange StartValue="30" EndValue="60" Background="Red" />
            </gauge:LinearAxis.Ranges>
            
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="25" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 3: Gauge with Multiple Pointers

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Maximum="140" Interval="10">
            <!-- Bar pointer for current value -->
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="90" />
            </gauge:LinearAxis.BarPointers>
            
            <!-- Shape pointer for threshold -->
            <gauge:LinearAxis.MarkerPointers>
                <gauge:LinearShapePointer Value="90"
                                          VerticalAnchor="End"
                                          OffsetPoint="0,-8" />
                
                <!-- Content pointer for label -->
                <gauge:LinearContentPointer Value="90"
                                            VerticalAnchor="End"
                                            OffsetPoint="0,-28">
                    <gauge:LinearContentPointer.Content>
                        <TextBlock Text="90%" />
                    </gauge:LinearContentPointer.Content>
                </gauge:LinearContentPointer>
            </gauge:LinearAxis.MarkerPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 4: Interactive Gauge with Draggable Pointer

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis ShowTicks="False"
                          AxisLineStroke="CornflowerBlue"
                          AxisLineStrokeThickness="30">
            <gauge:LinearAxis.MarkerPointers>
                <gauge:LinearShapePointer Value="30"
                                          IsInteractive="True"
                                          OffsetPoint="0,-15"
                                          VerticalAnchor="End"
                                          Fill="Indigo"
                                          ValueChanged="OnPointerValueChanged" />
            </gauge:LinearAxis.MarkerPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

private void OnPointerValueChanged(object sender, ValueChangedEventArgs e)
{
    // Handle value change
    double newValue = e.NewValue;
}

Pattern 5: Gauge with Color-Coded Ranges

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Maximum="140" Interval="10">
            <gauge:LinearAxis.Ranges>
                <gauge:LinearGaugeRange StartValue="0" EndValue="50" Background="Red" />
                <gauge:LinearGaugeRange StartValue="50" EndValue="100" Background="Orange" />
                <gauge:LinearGaugeRange StartValue="100" EndValue="140" Background="Green" />
            </gauge:LinearAxis.Ranges>
            
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="90" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 6: Animated Pointer Updates

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Interval="10">
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="60"
                                  EnableAnimation="True"
                                  AnimationDuration="1500">
                    <gauge:BarPointer.AnimationEasingFunction>
                        <CircleEase EasingMode="EaseOut" />
                    </gauge:BarPointer.AnimationEasingFunction>
                </gauge:BarPointer>
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 7: Gradient Bar Pointer

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis>
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="40">
                    <gauge:BarPointer.GradientStops>
                        <gauge:GaugeGradientStop Value="0" Color="#FFCC2B5E" />
                        <gauge:GaugeGradientStop Value="40" Color="#FF753A88" />
                    </gauge:BarPointer.GradientStops>
                </gauge:BarPointer>
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Pattern 8: ViewModel Data Binding

public class GaugeViewModel : INotifyPropertyChanged
{
    private double currentValue;
    
    public double CurrentValue
    {
        get => currentValue;
        set
        {
            currentValue = value;
            OnPropertyChanged(nameof(CurrentValue));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis>
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="{x:Bind ViewModel.CurrentValue, Mode=TwoWay}" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

Key Properties Reference

Gauge Properties (SfLinearGauge)

Property Type Description
Axis LinearAxis Gets or sets the linear axis configuration
IsInversed bool Gets or sets whether axis is inverted (right-to-left or bottom-to-top)
IsMirrored bool Gets or sets whether axis is mirrored (opposite side)
Orientation Orientation Gets or sets gauge orientation: Horizontal, Vertical

Axis Properties (LinearAxis)

Property Type Description
Minimum double Minimum value of the axis (default: 0)
Maximum double Maximum value of the axis (default: 100)
Interval double Interval between labels on the axis
ShowAxisLine bool Show or hide the axis line (default: true)
ShowLabels bool Show or hide axis labels (default: true)
ShowTicks bool Show or hide tick marks (default: true)
AxisLineStroke Brush Color of the axis line
AxisLineStrokeThickness double Thickness of the axis line
LabelPosition GaugeLabelsPosition Label position: Inside, Outside
LabelOffset double Distance between axis line and labels
LabelFormat string Format string for labels (e.g., "c" for currency)
TickPosition GaugeElementPosition Tick position: Inside, Outside, Cross
MajorTickLength double Length of major tick marks
MinorTickLength double Length of minor tick marks
MinorTicksPerInterval int Number of minor ticks per interval
UseRangeColorForAxis bool Apply range colors to axis labels and ticks

Pointer Properties (Base: LinearGaugePointer)

Property Type Description
Value double Current value of the pointer
EnableAnimation bool Enable pointer animation (default: false)
AnimationDuration double Animation duration in milliseconds (default: 1500)
AnimationEasingFunction EasingFunctionBase Easing function for animation

Bar Pointer Properties

Property Type Description
Background Brush Fill color of the bar pointer
PointerSize double Thickness of the bar pointer
CornerStyle CornerStyle Corner style: BothFlat, BothCurve, StartCurve, EndCurve
Offset double Distance from axis line (positive: inside, negative: outside)
GradientStops ObservableCollection Collection of gradient stops for color transition
Child UIElement Child content displayed inside the bar pointer

Shape Pointer Properties (LinearShapePointer)

Property Type Description
ShapeType GaugeShapeType Shape: Circle, Diamond, Triangle, InvertedTriangle, Rectangle
ShapeHeight double Height of the shape pointer
ShapeWidth double Width of the shape pointer
Fill Brush Fill color of the shape
Stroke Brush Border color of the shape
StrokeThickness double Border thickness of the shape
HasShadow bool Enable shadow effect (default: false)
IsInteractive bool Enable dragging (default: false)
ShapeTemplate DataTemplate Custom shape template
OffsetPoint Point X/Y offset from default position
HorizontalAnchor GaugeAnchor Horizontal alignment: Start, Center, End
VerticalAnchor GaugeAnchor Vertical alignment: Start, Center, End

Content Pointer Properties (LinearContentPointer)

Property Type Description
Content object Custom content (TextBlock, Image, etc.)
OffsetPoint Point X/Y offset from default position
HorizontalAnchor GaugeAnchor Horizontal alignment: Start, Center, End
VerticalAnchor GaugeAnchor Vertical alignment: Start, Center, End

Range Properties (LinearGaugeRange)

Property Type Description
StartValue double Start value of the range
EndValue double End value of the range
StartWidth double Width at range start
MidWidth double Width at range middle (optional)
EndWidth double Width at range end
Background Brush Fill color of the range
RangePosition GaugeElementPosition Position: Inside, Outside, Cross
GradientStops ObservableCollection Collection of gradient stops for color transition
Child UIElement Child content displayed inside the range

Common Use Cases

Temperature Gauge for Weather App

Create vertical temperature gauges displaying current temperature with color-coded ranges (blue for cold, orange for moderate, red for hot) and animated pointer transitions.

Battery Level Indicator

Build horizontal battery level gauges with green/yellow/red ranges, bar pointers showing charge level, and content pointers displaying percentage text.

Speed Meter for Vehicle Dashboard

Implement horizontal or vertical speed gauges with tick marks every 10 units, shape pointers for current speed, and range indicators for speed limits.

Progress Bar with Percentage

Create progress indicators using bar pointers with rounded corners, child content displaying percentage text, and smooth animations as values update.

Pressure Gauge for Industrial Monitoring

Design pressure gauges with custom axis ranges, multiple ranges for safe/warning/danger zones, and interactive pointers for threshold adjustment.

Volume Control Slider

Build interactive volume controls using horizontal gauges with draggable shape pointers, custom axis styling, and value change events for audio level adjustment.

Data Analytics Dashboard

Create dashboard panels with multiple linear gauges showing KPIs, each with different orientations, color schemes, and ranges for performance visualization.

System Resource Monitor

Implement CPU/memory/disk usage gauges with animated bar pointers, gradient fills showing resource consumption, and real-time value updates.

Next Steps: Read the reference documentation above based on what you need to implement. Start with getting-started.md for initial setup, then explore specific features as needed.

Weekly Installs
5
Repository
syncfusion/winu…s-skills
First Seen
1 day ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode5
gemini-cli5
deepagents5
antigravity5
github-copilot5
codex5