Implementing Syncfusion Blazor Charts

A comprehensive guide for implementing the Syncfusion Blazor Chart component to create interactive, feature-rich data visualizations in Blazor applications. The Chart component supports 33+ chart types, multiple axes, advanced interactivity, and extensive customization options.

When to Use This Skill

Use this skill when you need to:

Create data visualizations in Blazor applications (line, column, bar, area, etc.)
Implement financial charts for stock analysis (candle, HILO, HILOOC)
Build statistical visualizations (histogram, box-whisker, pareto, waterfall)
Display comparative data with stacked or grouped charts
Show range-based data with range area/column charts
Create polar or radar charts for circular data representation
Add interactive features like tooltips, zooming, crosshair, selection
Customize chart appearance with themes, gradients, annotations
Handle dynamic data with live updates and data editing
Implement accessible charts with ARIA support and internationalization

Component Overview

The Syncfusion Blazor Chart component is a powerful data visualization tool that provides:

33+ Chart Types: Line, Column, Bar, Area, Spline, Scatter, Bubble, Candle, HILO, Polar, Radar, and more
Multiple Axes: Support for category, numeric, datetime, and logarithmic axes
Rich Interactivity: Zooming, panning, crosshair, trackball, tooltips, selection
Data Binding: Work with List, DataManager, dynamic updates, and live data
Visual Elements: Markers, data labels, annotations, legends, gradients
Advanced Features: Technical indicators, trend lines, strip lines, multiple panes
Accessibility: Full ARIA support, keyboard navigation, localization, RTL
Customization: Themes, responsive design, print support, adaptive layout

Documentation and Navigation Guide

Complete API Reference

📄 Read: references/api-reference.md

CRITICAL: Use this reference FIRST for all API-related questions

Use this authoritative API reference when:

Looking up correct enum values (ChartSeriesType, ValueType, SelectionMode, etc.)
Finding public method signatures (RefreshAsync, ExportAsync, ShowTooltip, etc.)
Verifying property names and types
Generating code samples
Troubleshooting API-related issues

Topics covered:

Complete list of SfChart public methods with signatures
All chart enumerations with correct values
Key component classes and their properties
Method usage examples
Common patterns and best practices

Key Points:

All enum values are exact - do not use variations
Method names follow C# conventions (e.g., RefreshAsync not Refresh)
Always use @ref to access chart instance for method calls
Namespace: Syncfusion.Blazor.Charts

Getting Started

📄 Read: references/getting-started.md

Use this when:

Setting up a new Blazor Chart project
Installing NuGet packages and configuring services
Creating your first chart component
Understanding basic chart structure and data binding
Working with Visual Studio, VS Code, or .NET CLI

Topics covered:

Installation and prerequisites
Package setup (Syncfusion.Blazor.Charts)
Namespace imports and service registration
Script references
Basic chart implementation
Simple data binding example

Chart Types

Common Chart Types

📄 Read: references/chart-types-common.md

Use this for frequently-used chart types:

Line charts for trend visualization
Area charts for showing magnitude over time
Column charts for categorical comparisons
Bar charts for horizontal comparisons
Spline charts for smooth curves
Step charts for stepped data progression

Topics covered:

Line, Area, Column, Bar chart implementations
Spline and Spline Area variations
Step Line and Step Area patterns
When to use each chart type
Configuration and customization
Multi-series examples

Specialized Chart Types

📄 Read: references/chart-types-specialized.md

Use this for specialized visualization needs:

Financial charts (Candle, HILO, HILOOC)
Statistical charts (Box-Whisker, Histogram, Error Bar, Pareto, Waterfall)
Stacked charts (Stack Area/Bar/Column/Line)
Range charts (Range Area/Column/Step Area)
Polar and Radar charts
Scatter and Bubble charts
Vertical chart orientation

Topics covered:

Financial chart patterns and configurations
Statistical analysis chart types
Stacking modes (normal vs 100%)
Range visualization techniques
Circular chart layouts
XY scatter relationships
Chart orientation options

Axes and Data Configuration

📄 Read: references/axes-and-scales.md

Use this when:

Configuring axis types (category, numeric, datetime, logarithmic)
Customizing axis appearance and behavior
Formatting axis labels and values
Working with multiple axes
Setting axis ranges and intervals

Topics covered:

Category axis for discrete data
Numeric axis for continuous values
DateTime axis for time-series data
Logarithmic axis for exponential data
Axis customization (title, range, interval)
Label formatting, rotation, and positioning
Multiple axis configuration
Inverse and opposed axes

📄 Read: references/data-handling.md

Use this when:

Binding data sources to charts
Adding, removing, or updating data dynamically
Enabling data editing
Sorting chart data
Working with live or streaming data

Topics covered:

Data source binding (List, DataManager)
Dynamic data operations
Data editing functionality
Chart sorting options
Real-time data updates
Data serialization patterns

Visual Elements

📄 Read: references/visual-elements.md

Use this when:

Adding data markers to chart points
Displaying data labels on series
Creating custom label templates
Adding annotations (text, shapes, images)
Applying gradient fills

Topics covered:

Data marker types and customization
Data label visibility and formatting
Label positioning strategies
Data label templates
Last data label highlighting
Chart annotations (text, shapes, images)
Gradient color fills

📄 Read: references/legend.md

Use this when:

Enabling and configuring chart legend
Positioning legend (top, bottom, left, right)
Customizing legend appearance
Implementing legend click behavior
Creating custom legend templates

Topics covered:

Legend visibility and positioning
Legend shape and text customization
Interactive legend (toggle series)
Legend pagination
Custom legend templates
Legend alignment options

Interactive Features

📄 Read: references/interactive-features.md

Use this when:

Enabling tooltips with custom formatting
Adding crosshair or trackball for data tracking
Implementing point, series, or cluster selection
Enabling zooming and panning
Creating interactive user experiences

Topics covered:

Tooltip configuration and templates
Crosshair and trackball features
Selection modes and patterns
Zoom types (selection, pinch, mousewheel)
Zoom toolbar configuration
Pan functionality
User interaction events

Customization and Appearance

📄 Read: references/appearance-styling.md

Use this when:

Customizing chart appearance and themes
Setting chart dimensions and sizing
Configuring responsive/adaptive layout
Enabling print functionality
Styling background, borders, and margins

Topics covered:

Chart appearance customization
Theme configuration
Chart dimensions and sizing
Responsive design patterns
Adaptive layout for mobile
Print support
Background and border styling
Gradient customization

📄 Read: references/advanced-features.md

Use this when:

Adding technical indicators (EMA, SMA, RSI, etc.)
Implementing trend lines (linear, exponential, polynomial)
Creating strip lines (horizontal/vertical bands)
Using multiple panes (sub-charts)
Handling empty points

Topics covered:

Technical indicators for financial charts
Trend line types and configuration
Strip line patterns
Multiple pane layouts
Empty point handling strategies
Row and column definitions

Accessibility and Internationalization

📄 Read: references/accessibility-internationalization.md

Use this when:

Implementing accessible charts (ARIA, keyboard nav)
Configuring advanced accessibility features
Enabling internationalization (i18n)
Setting up localization (l10n)
Supporting RTL layouts

Topics covered:

Accessibility features and ARIA support
Keyboard navigation patterns
Advanced accessibility configuration
Internationalization setup
Localization resources
RTL support
Screen reader compatibility

Events

📄 Read: references/events.md

Use this when:

Handling chart lifecycle events
Responding to user interactions (clicks, mouse events)
Listening to axis, series, or point events
Implementing custom event handlers
Triggering actions on zoom, pan, or selection

Topics covered:

Chart load and render events
Point and series events
Mouse events (click, move, leave)
Axis label render events
Legend events
Zoom and pan events
Selection events
Event handler patterns

Practical Examples and How-To Guides

📄 Read: references/practical-examples.md

Use this for common implementation scenarios:

Adding/removing series dynamically
Hiding axes programmatically
Converting milliseconds to datetime
Updating points dynamically
Implementing lazy loading
Creating live/real-time charts
Getting selected data
Synchronizing multiple charts
Adding threshold lines
Custom tooltip tables

Topics covered:

Dynamic series management
Axis visibility control
Date conversion techniques
Dynamic point updates
Lazy loading patterns
Live chart implementation
Selection data retrieval
Chart synchronization
Threshold line implementation
Custom tooltip tables

Public Methods Reference

The SfChart component provides several public methods for programmatic control. Always use @ref to access these methods:

Essential Methods

<SfChart @ref="ChartRef">
    <!-- Configuration -->
</SfChart>

@code {
    SfChart ChartRef;
    
    // Refresh the chart
    async Task RefreshChart() => await ChartRef.RefreshAsync();
    
    // Export the chart
    async Task ExportChart() => await ChartRef.ExportAsync(ExportType.PNG, "chart.png");
    
    // Print the chart
    async Task PrintChart() => await ChartRef.PrintAsync();
    
    // Show/Hide tooltip
    void ShowChartTooltip() => ChartRef.ShowTooltip("January", 35);
    void HideChartTooltip() => ChartRef.HideTooltip();
    
    // Show/Hide crosshair
    void ShowChartCrosshair() => ChartRef.ShowCrosshair(100, 50);
    void HideChartCrosshair() => ChartRef.HideCrosshair();
    
    // Selection control
    void ClearSelections() => ChartRef.ClearSelection();
    
    // Sorting
    void SortData() => ChartRef.Sort("YValue", ListSortDirection.Descending);
    void ClearChartSort() => ChartRef.ClearSort();
}

See references/api-reference.md for complete method documentation.

⚠️ CRITICAL: API Usage Guidelines

1. Enum Names - MUST Use Full Namespace

Syncfusion Blazor Charts requires FULLY QUALIFIED enum names:

<!-- ✅ CORRECT - Use full namespace -->
<ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category" />
<ChartSeries Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column" />

<!-- ❌ WRONG - Short form will cause errors -->
<ChartPrimaryXAxis ValueType="ValueType.Category" />
<ChartSeries Type="ChartSeriesType.Column" />

Always use Syncfusion.Blazor.Charts. prefix for:

ValueType (Category, Double, DateTime, etc.)
ChartSeriesType (Column, Line, Area, etc.)
LegendPosition, SelectionMode, ZoomMode, ChartShape, etc.

2. Component Property Restrictions

⚠️ Common Property Errors to Avoid:

ChartCrosshairLine - Limited Properties

<!-- ✅ CORRECT - Only Width and Color supported -->
<ChartCrosshairSettings Enable="true">
    <ChartCrosshairLine Width="1" Color="#666"></ChartCrosshairLine>
</ChartCrosshairSettings>

<!-- ❌ WRONG - DashArray NOT supported on ChartCrosshairLine -->
<ChartCrosshairLine Width="1" Color="#666" DashArray="5,5"></ChartCrosshairLine>

Supported ChartCrosshairLine Properties:

Width - Line width (number)
Color - Line color (string)

NOT Supported:

❌ DashArray - Will cause runtime error
❌ Opacity - Not available on this component

Striplines - Use Plural Form

<!-- ✅ CORRECT - ChartStriplines (plural) -->
<ChartPrimaryYAxis>
    <ChartStriplines>
        <ChartStripline Start="50" End="60" Color="red" />
    </ChartStriplines>
</ChartPrimaryYAxis>

<!-- ❌ WRONG - ChartAxisStripLineSettings does not exist -->
<ChartAxisStripLineSettings>
    <ChartAxisStripLine Start="50" End="60" />
</ChartAxisStripLineSettings>

3. Validation Checklist

Before deploying, verify:

✅ All enums use Syncfusion.Blazor.Charts. prefix
✅ ChartCrosshairLine uses ONLY Width and Color
✅ Striplines use <ChartStriplines> and <ChartStripline>
✅ Component references use @ref for method access
✅ Property names match official API exactly (case-sensitive)

Quick Start Example

Here's a minimal example to create a column chart with data:

@page "/chart-demo"
@using Syncfusion.Blazor.Charts

<SfChart Title="Sales Analysis">
    <ChartPrimaryXAxis Title="Month" ValueType="Syncfusion.Blazor.Charts.ValueType.Category">
    </ChartPrimaryXAxis>
    
    <ChartPrimaryYAxis Title="Sales in Dollar">
    </ChartPrimaryYAxis>
    
    <ChartTooltipSettings Enable="true"></ChartTooltipSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@SalesData" 
                     Name="Sales" 
                     XName="Month" 
                     YName="SalesValue" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
            <ChartMarker>
                <ChartDataLabel Visible="true"></ChartDataLabel>
            </ChartMarker>
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

@code {
    public class SalesInfo
    {
        public string Month { get; set; }
        public double SalesValue { get; set; }
    }

    public List<SalesInfo> SalesData = new List<SalesInfo>
    {
        new SalesInfo { Month = "Jan", SalesValue = 35 },
        new SalesInfo { Month = "Feb", SalesValue = 28 },
        new SalesInfo { Month = "Mar", SalesValue = 34 },
        new SalesInfo { Month = "Apr", SalesValue = 32 },
        new SalesInfo { Month = "May", SalesValue = 40 },
        new SalesInfo { Month = "Jun", SalesValue = 32 }
    };
}

Prerequisites:

Install Syncfusion.Blazor.Charts NuGet package
Add @using Syncfusion.Blazor.Charts to _Imports.razor
Register service: builder.Services.AddSyncfusionBlazor(); in Program.cs
Add script reference in App.razor

Common Patterns

Multi-Series Comparison Chart

<SfChart Title="Product Sales Comparison">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@Product1Sales" XName="Month" YName="Sales" 
                     Name="Product 1" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
        <ChartSeries DataSource="@Product2Sales" XName="Month" YName="Sales" 
                     Name="Product 2" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true"></ChartLegendSettings>
</SfChart>

Time-Series Line Chart with Zooming

<SfChart>
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime" 
                        Title="Date">
    </ChartPrimaryXAxis>
    
    <ChartZoomSettings EnableSelectionZooming="true" 
                       EnablePan="true" 
                       EnableMouseWheelZooming="true">
    </ChartZoomSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@TimeSeriesData" 
                     XName="Date" 
                     YName="Value" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Line">
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

Stacked Area Chart with Legend

<SfChart Title="Resource Allocation">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@ResourceData1" XName="Period" YName="Hours" 
                     Name="Development" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData2" XName="Period" YName="Hours" 
                     Name="Testing" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData3" XName="Period" YName="Hours" 
                     Name="Documentation" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true" Position="Syncfusion.Blazor.Charts.LegendPosition.Bottom">
    </ChartLegendSettings>
</SfChart>

Key Configuration Properties

Chart Component (`SfChart`)

Title - Chart title text
Width / Height - Chart dimensions (accepts px or %, default: "100%")
Theme - Visual theme (see Theme enum in API reference)
Background - Chart background color
EnableAnimation - Enable/disable animation (default: true)
SelectionMode - Selection mode (None, Series, Point, Cluster, DragXY, DragX, DragY, Lasso)
HighlightMode - Highlight mode (None, Series, Point, Cluster)

Primary Axes (`ChartPrimaryXAxis`, `ChartPrimaryYAxis`)

ValueType - Axis type: Syncfusion.Blazor.Charts.ValueType.Category, ValueType.Double, ValueType.DateTime, ValueType.Logarithmic, ValueType.DateTimeCategory
Title - Axis title
Minimum / Maximum - Axis range
Interval - Spacing between labels
LabelFormat - Format string for labels (e.g., "C0", "N2", "dd MMM")
EdgeLabelPlacement - Edge label handling (None, Hide, Shift)
LabelIntersectAction - Label intersection handling (None, Hide, Trim, Wrap, MultipleRows, Rotate45, Rotate90)
Striplines - Use <ChartStriplines> (plural) for horizontal/vertical bands

Series (`ChartSeries`)

DataSource - Data collection (IEnumerable)
XName / YName - Property names for X and Y values (case-sensitive)
Type - Chart type: Syncfusion.Blazor.Charts.ChartSeriesType.Column, ChartSeriesType.Line, etc. (see API reference)
Name - Series name for legend
Fill - Series color (CSS color string)
Width - Line/border width (pixels)
DashArray - Dash pattern (e.g., "5,5")
Opacity - Transparency (0 to 1)

Interactivity

ChartTooltipSettings - Tooltip configuration
- Enable - Show/hide tooltip
- Shared - Enable shared tooltip for multiple series
- Format - Custom tooltip format
- Template - Custom tooltip template (RenderFragment)
ChartZoomSettings - Zoom and pan options
- EnableSelectionZooming - Enable selection-based zoom
- EnableMouseWheelZooming - Enable mouse wheel zoom
- EnablePinchZooming - Enable pinch zoom (touch devices)
- EnablePan - Enable panning
- Mode - Zoom mode (X, Y, XY)
SelectionMode - Selection behavior (see SelectionMode enum)
ChartCrosshairSettings - Crosshair configuration
- Enable - Show/hide crosshair
- LineType - Crosshair line type (Vertical, Horizontal, Both)
- ChartCrosshairLine - Line style (Width, Color ONLY - NO DashArray)

Visual Elements

ChartMarker - Data point markers
- Visible - Show/hide markers
- Shape - Marker shape (see ChartShape enum)
- Width / Height - Marker dimensions
ChartDataLabel - Data labels on points
- Visible - Show/hide labels
- Position - Label position
- Template - Custom label template
ChartLegendSettings - Legend configuration
- Visible - Show/hide legend
- Position - Legend position (see LegendPosition enum)
ChartAnnotations - Custom annotations
- Support for text, images, and shapes

Additional Resources

Official Documentation: Syncfusion Blazor Chart Documentation
API Reference: Chart API
Live Demos: Blazor Chart Demos

syncfusion-blazor-charts

Implementing Syncfusion Blazor Charts

When to Use This Skill

Component Overview

Documentation and Navigation Guide

Complete API Reference

Getting Started

Chart Types

Common Chart Types

Specialized Chart Types

Axes and Data Configuration

Visual Elements

Interactive Features

Customization and Appearance

Accessibility and Internationalization

Events

Practical Examples and How-To Guides

Public Methods Reference

Essential Methods

⚠️ CRITICAL: API Usage Guidelines

1. Enum Names - MUST Use Full Namespace

2. Component Property Restrictions

ChartCrosshairLine - Limited Properties

Striplines - Use Plural Form

3. Validation Checklist

Quick Start Example

Common Patterns

Multi-Series Comparison Chart

Time-Series Line Chart with Zooming

Stacked Area Chart with Legend

Key Configuration Properties

Chart Component (SfChart)

Primary Axes (ChartPrimaryXAxis, ChartPrimaryYAxis)

Series (ChartSeries)

Interactivity

Visual Elements

Additional Resources

Chart Component (`SfChart`)

Primary Axes (`ChartPrimaryXAxis`, `ChartPrimaryYAxis`)

Series (`ChartSeries`)