syncfusion-blazor-linear-gauge

# Implementing Syncfusion Blazor Linear Gauges **NuGet:** `Syncfusion.Blazor.LinearGauge` + `Syncfusion.Blazor.Themes` **Namespace:** `Syncfusion.Blazor.LinearGauge` ## When to Use This Skill Use this skill when the user needs to: - **Visualize numeric values** on a linear scale (horizontal or vertical) - **Display measurement data** like temperature, pressure, speed, or progress - **Create dashboard components** with gauge visualizations - **Implement KPI displays** with ranges and indicators - **Show real-time data** with animated pointers - **Build interactive gauges** where users can drag pointers to change values - **Create multi-scale visualizations** with multiple axes and pointers The Syncfusion Blazor Linear Gauge is ideal for applications requiring precise numeric visualization with customizable scales, pointers, and ranges. --- ## Component Overview The **Blazor Linear Gauge (SfLinearGauge)** is a data visualization component that displays numeric values on a linear scale with features including: - **Multiple axes** with customizable ranges and styling - **Various pointer types** (marker shapes, bar pointers, text, images) - **Color-coded ranges** for value categorization - **Annotations** for labels and custom content - **Interactive features** including drag-to-change pointer values - **Events and methods** for dynamic updates - **Accessibility support** with WCAG compliance - **Internationalization** for global applications --- ## Documentation and Navigation Guide This skill provides comprehensive, self-contained reference files for each aspect of the Linear Gauge component. Read the appropriate reference based on your current need. ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) **When to read:** First-time setup, new project initialization, installation questions **What's covered:** - Installation via Visual Studio, VS Code, and .NET CLI - NuGet package installation (Syncfusion.Blazor.LinearGauge, Syncfusion.Blazor.Themes) - Namespace imports and service registration - Stylesheet and script references - Basic LinearGauge component implementation - Adding pointers and setting values - Adding titles and ranges - Running your first gauge application ### Core Components #### Axes Configuration 📄 **Read:** [references/axes-configuration.md](references/axes-configuration.md) **When to read:** Setting up gauge scales, customizing axis appearance, working with multiple axes **What's covered:** - Setting Minimum and Maximum values for the scale - Line customization (height, width, color, offset) - Major ticks configuration (interval, height, color, width, position, offset) - Minor ticks configuration (interval, height, color, width, position, offset) - Label customization (format, font, position, offset) - Multiple axes on single gauge - Inverse axis direction - Opposed position for axes - Complete code examples for all configurations #### Pointers 📄 **Read:** [references/pointers.md](references/pointers.md) **When to read:** Adding value indicators, customizing pointer appearance, implementing multiple pointers **What's covered:** - Setting pointer values - Marker pointers with various shapes (Circle, Rectangle, Triangle, Diamond, InvertedTriangle) - Bar pointers with customization options - Image pointers with custom images - Text pointers with custom styling - Pointer positioning and placement - Animation configuration for smooth transitions - Multiple pointers on single axis - Drag and drop interaction for value changes - Complete examples for each pointer type #### Ranges 📄 **Read:** [references/ranges.md](references/ranges.md) **When to read:** Adding color-coded value regions, implementing performance zones, creating visual thresholds **What's covered:** - Setting range start and end values - Range color customization - Range positioning (inside, outside, cross) - Range offset configuration - Start and end width for gradient effects - Multiple ranges on single axis - Practical use cases (temperature zones, performance indicators, status ranges) - Complete code examples with visual results ### Appearance and Styling #### Annotations 📄 **Read:** [references/annotations.md](references/annotations.md) **When to read:** Adding labels, custom content, units, or dynamic text to the gauge **What's covered:** - Adding text annotations - HTML content in annotations - Positioning annotations with x, y coordinates - Z-index for layering multiple annotations - Font styling for text annotations - Horizontal and vertical alignment - Multiple annotations on gauge - Dynamic content updates - Practical examples (unit labels, value displays, warnings) #### Appearance and Styling 📄 **Read:** [references/appearance-and-styling.md](references/appearance-and-styling.md) **When to read:** Customizing gauge look and feel, theming, responsive design, print styling **What's covered:** - Container customization (width, height, background, border) - Orientation (horizontal vs vertical) - Margin and container adjustments - Title customization (text, font, position) - Theme selection (Bootstrap, Material, Fabric, Fluent, Tailwind, etc.) - Custom CSS styling - Responsive design considerations - Color schemes and palettes - Print-friendly styling - Complete styling examples ### Advanced Features #### Methods and Events 📄 **Read:** [references/methods-and-events.md](references/methods-and-events.md) **When to read:** Implementing dynamic updates, handling user interactions, programmatic control **What's covered:** - setPointerValue() method for dynamic pointer updates - setAnnotationValue() method for annotation updates - print() method for printing gauges - refresh() method for re-rendering - Load and Loaded events - AnimationComplete event - AxisLabelRendering event for label customization - AnnotationRendering event - ValueChange event for user interactions - TooltipRendering event - ResizeCompleted event - Complete event handler examples with practical scenarios #### User Interaction 📄 **Read:** [references/user-interaction.md](references/user-interaction.md) **When to read:** Enabling tooltips, drag interactions, mouse/touch events, value changes **What's covered:** - Tooltip configuration and customization - Tooltip templates with custom HTML - Pointer drag to change values - Enabling/disabling pointer interaction - Mouse and touch event handling - Value change tracking and callbacks - Animation on user interaction - Complete interactive examples ### Accessibility and Internationalization 📄 **Read:** [references/accessibility-and-internationalization.md](references/accessibility-and-internationalization.md) **When to read:** Implementing WCAG compliance, keyboard navigation, screen readers, global applications **What's covered:** - Accessibility overview (WCAG 2.1 Level AA compliance) - Keyboard navigation support - Screen reader compatibility - ARIA attributes and labels - High contrast mode support - Focus indicators - Internationalization (i18n) setup - Number formatting for different locales - RTL (Right-to-Left) support - Complete accessibility implementation examples --- ## Quick Start Example Here's a minimal example to get started with Blazor Linear Gauge: ```razor @using Syncfusion.Blazor.LinearGauge <SfLinearGauge Title="Temperature Monitor"> <LinearGaugeAxes> <LinearGaugeAxis Minimum="0" Maximum="120"> <LinearGaugeAxisLabelStyle Format="{value}°C"></LinearGaugeAxisLabelStyle> <LinearGaugePointers> <LinearGaugePointer PointerValue="65" Color="#007bff"> </LinearGaugePointer> </LinearGaugePointers> <LinearGaugeRanges> <LinearGaugeRange Start="0" End="40" Color="#4CAF50"></LinearGaugeRange> <LinearGaugeRange Start="40" End="80" Color="#FFC107"></LinearGaugeRange> <LinearGaugeRange Start="80" End="120" Color="#F44336"></LinearGaugeRange> </LinearGaugeRanges> </LinearGaugeAxis> </LinearGaugeAxes> </SfLinearGauge> ``` **Result:** A vertical linear gauge showing temperature from 0°C to 120°C with three color-coded ranges (green, yellow, red) and a pointer at 65°C. --- ## Common Patterns ### Pattern 1: Simple Progress Indicator **Use case:** Show completion percentage or progress status ```razor @using Syncfusion.Blazor.LinearGauge <SfLinearGauge Orientation="Syncfusion.Blazor.LinearGauge.Orientation.Horizontal" Width="400px" Height="80px"> <LinearGaugeAxes> <LinearGaugeAxis Minimum="0" Maximum="100"> <LinearGaugePointers> <LinearGaugePointer PointerValue="75" Type="Syncfusion.Blazor.LinearGauge.Point.Bar" Color="#28a745" Width="20"> </LinearGaugePointer> </LinearGaugePointers> </LinearGaugeAxis> </LinearGaugeAxes> </SfLinearGauge> ``` ### Pattern 2: Multi-Scale Dashboard Gauge **Use case:** Display multiple metrics on one gauge ```razor @using Syncfusion.Blazor.LinearGauge <SfLinearGauge> <LinearGaugeAxes> <LinearGaugeAxis Minimum="0" Maximum="100"> <LinearGaugePointers> <LinearGaugePointer PointerValue="60" Color="#007bff"></LinearGaugePointer> <LinearGaugePointer PointerValue="80" Color="#dc3545"></LinearGaugePointer> </LinearGaugePointers> </LinearGaugeAxis> </LinearGaugeAxes> </SfLinearGauge> ``` ### Pattern 3: Interactive Value Adjuster **Use case:** Allow users to change values by dragging the pointer ```razor @using Syncfusion.Blazor.LinearGauge <SfLinearGauge> <LinearGaugeEvents ValueChange="@OnValueChange"></LinearGaugeEvents> <LinearGaugeAxes> <LinearGaugeAxis Minimum="0" Maximum="100"> <LinearGaugePointers> <LinearGaugePointer PointerValue="@currentValue" EnableDrag="true"> </LinearGaugePointer> </LinearGaugePointers> </LinearGaugeAxis> </LinearGaugeAxes> </SfLinearGauge> @code { private double currentValue = 50; private void OnValueChange(ValueChangeEventArgs args) { currentValue = args.Value; } } ``` ### Pattern 4: Styled Thermometer **Use case:** Temperature display with visual zones ```razor @using Syncfusion.Blazor.LinearGauge <SfLinearGauge Width="150px" Height="400px"> <LinearGaugeAxes> <LinearGaugeAxis Minimum="-20" Maximum="120"> <LinearGaugeAxisLabelStyle Format="{value}°"> </LinearGaugeAxisLabelStyle> <LinearGaugePointers> <LinearGaugePointer PointerValue="@temperature" Type="Syncfusion.Blazor.LinearGauge.Point.Bar" Color="#ff6b6b" Width="20"> </LinearGaugePointer> </LinearGaugePointers> <LinearGaugeRanges> <LinearGaugeRange Start="-20" End="0" Color="#0099ff"></LinearGaugeRange> <LinearGaugeRange Start="0" End="25" Color="#00e676"></LinearGaugeRange> <LinearGaugeRange Start="25" End="120" Color="#ff5252"></LinearGaugeRange> </LinearGaugeRanges> </LinearGaugeAxis> </LinearGaugeAxes> </SfLinearGauge> @code { private double temperature = 35; } ``` --- ## API Reference The official Linear Gauge API is centered on the `SfLinearGauge` component and comprehensive child components for configuring axes, pointers, ranges, annotations, gradients, tooltips, and event handlers. This reference is based on the official [Syncfusion Blazor Linear Gauge API documentation](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.LinearGauge.html). ### SfLinearGauge Primary container component for the gauge. This is the root component that hosts all gauge elements. **Component Properties:** **Sizing & Layout:** - `Width` (string): Sets the width of the linear gauge container - `Height` (string): Sets the height of the linear gauge container - `Orientation` (Orientation): Sets the gauge orientation (`Horizontal` or `Vertical`) - `Description` (string): Sets the description for accessibility purposes **Appearance:** - `Title` (string): Sets the title text displayed on the gauge - `TitleStyle` (LinearGaugeTitleStyle): Configures title font, position, and styling - `Background` (string): Sets the background color of the gauge container - `Theme` (Theme): Applies predefined themes (Bootstrap, Material, Fabric, Fluent, Tailwind, etc.) - `Container` (LinearGaugeContainer): Configures the container appearance and border - `Margin` (LinearGaugeMargin): Sets left, right, top, and bottom margins **Behavior:** - `AnimationDuration` (double): Sets the animation duration (in milliseconds) for initial rendering and pointer updates - `Format` (string): Sets the number format for axis labels - `EnableGroupingSeparator` (bool): Enables thousand separators in numbers - `ID` (string): Sets the unique identifier for the gauge component - `TabIndex` (int): Sets the tab order for keyboard navigation **Export & Print:** - `AllowPrint` (bool): Enables print functionality - `AllowPdfExport` (bool): Enables PDF export functionality - `AllowImageExport` (bool): Enables image export (PNG, SVG) functionality - `AllowMargin` (bool): Includes margins when printing or exporting **Styling:** - `RangePalettes` (string[]): Defines automatic color palette for ranges **Methods:** ```csharp // Update pointer value programmatically (async version) public async Task SetPointerValueAsync(int axisIndex, int pointerIndex, double value) // Update annotation content dynamically (async version) public async Task SetAnnotationValueAsync(int annotationIndex, string content) // Refresh the entire gauge (async version) public async Task RefreshAsync() // Print the gauge (requires AllowPrint="true") public async Task PrintAsync() // Export gauge to file (requires corresponding AllowXyzExport="true") public async Task ExportAsync(ExportType type, string fileName, PdfPageOrientation? orientation = null, bool allowDownload = true) ``` **Export Types:** - `ExportType.PNG` - `ExportType.SVG` - `ExportType.PDF` ### LinearGaugeAxes & LinearGaugeAxis Container (`LinearGaugeAxes`) for one or more axes. Each `LinearGaugeAxis` defines a scale with range, ticks, labels, pointers, and ranges. **LinearGaugeAxis Properties:** **Scale Configuration:** - `Minimum` (double): Sets the minimum value of the axis scale - `Maximum` (double): Sets the maximum value of the axis scale - `IsInversed` (bool): Reverses the direction of the axis (high to low instead of low to high) - `OpposedPosition` (bool): Places the axis on the opposite side (left/right for vertical, top/bottom for horizontal) - `ShowLastLabel` (bool): Shows or hides the last label on the axis **Child Components:** - `LinearGaugeLine` - Configures the axis line appearance - `LinearGaugeMajorTicks` - Major tick marks on the axis - `LinearGaugeMinorTicks` - Minor tick marks on the axis - `LinearGaugeAxisLabelStyle` - Label styling and positioning - `LinearGaugeAxisLabelFont` - Font properties for axis labels - `LinearGaugeContainer` - Container for the axis - `LinearGaugePointers` - Pointer collection for this axis - `LinearGaugeRanges` - Range collection for this axis - `LinearGaugeLinearGradient` - Gradient fill for axis elements - `LinearGaugeRadialGradient` - Radial gradient for axis elements ### Axis Line & Ticks **LinearGaugeLine** - Defines the axis line appearance - `Height` (double): Height of the axis line - `Width` (double): Width of the axis line - `Color` (string): Color of the axis line - `Offset` (double): Offset from axis **LinearGaugeMajorTicks** - Major tick configuration - `Interval` (double): Interval between major ticks