Migrate from Xamarin.Forms SfChart to .NET MAUI SfCartesianChart

30 Oct 202422 minutes to read

The Cartesian Chart was created from the scratch using the upgraded APIs and performance of the .NET MAUI graphics library and framework layouts. However, a minor code change is required. In addition, SfChart has been divided into five chart controls in .NET MAUI for a better user experience and understanding.

Xamarin .NET MAUI
SfChart
SfCartesianChart
SfCircularChart
SfFunnelChart
SfPyramidChart
SfPolarChart

To make the migration easier, the majority of the APIs from the Xamarin SfChart were kept in the .NET MAUI SfCartesianChart. Currently, most of the features have been added in the SfCartesianChart, but only a few are pending in the .NET MAUI along with some limitations. Please refer to the following details and the API migration information available below.

API migration

To initialize the control, import the Chart namespace and Initialize SfCartesianChart as shown in the following code sample.

Xamarin 
<ContentPage
    . . .
    xmlns:chart="clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms">

    <chart:SfChart/>
</ContentPage>
using Syncfusion.SfChart.XForms;
...

SfChart chart = new SfChart(); 
this.Content = chart;
.NET MAUI 
<ContentPage
    . . .    
    xmlns:chart="clr-namespace:Syncfusion.Maui.Charts;assembly=Syncfusion.Maui.Charts">
   
    <chart:SfCartesianChart/>
</ContentPage>
using Syncfusion.Maui.Charts;
. . .
SfCartesianChart chart = new SfCartesianChart(); 
this.Content = chart;

The following table illustrates the API migration for the chart.

Xamarin .NET MAUI
Title Title
Legend Legend
Series Series
PrimaryAxis XAxes
SecondaryAxis YAxes
SideBySideSeriesPlacement EnableSideBySideSeriesPlacement
ColorModel, CustomBrushes PaletteBrushes
ChartBehaviors TooltipBehavior, SelectionBehavior, ZoomPanBehavior

Axis

Xamarin .NET MAUI
AutoScrollingDelta AutoScrollingDelta
AutoScrollingMode AutoScrollingMode
AutoScrollingDeltaType AutoScrollingDeltaType
LabelRotationAngle LabelRotation
OpposedPosition CrossesAt
- CrossAxisName
PlotOffset PlotOffsetStart, PlotOffsetEnd
ShowTrackballInfo ShowTrackballLabel
LabelExtent LabelExtent
VisibleMinimum VisibleMinimum
VisibleMaximum VisibleMaximum
VisibleLabels VisibleLabels
LabelClicked Upcoming
TickPosition TickPosition
MaximumLabels Upcoming
LabelsIntersectAction LabelsIntersectAction
TrackballLabelTemplate TrackballLabelTemplate

The following code example explains how to migrate the axis of Xamarin SfChart to .NET MAUI SfCartesianChart.

Xamarin 
<chart:SfChart>  
    <chart:SfChart.PrimaryAxis>
	     <chart:NumericalAxis/>
    </chart:SfChart.PrimaryAxis>

    <chart:SfChart.SecondaryAxis>
	     <chart:NumericalAxis/>
    </chart:SfChart.SecondaryAxis>
</chart:SfChart>
SfChart chart = new SfChart();

CategoryAxis primaryAxis = new CategoryAxis();
chart.PrimaryAxis = primaryAxis;

NumericalAxis secondaryAxis = new NumericalAxis();
chart.SecondaryAxis = secondaryAxis;

this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>                            
    <chart:SfCartesianChart.XAxes>
        <chart:NumericalAxis/>
    </chart:SfCartesianChart.XAxes>
    
    <chart:SfCartesianChart.YAxes>
        <chart:NumericalAxis/>
    </chart:SfCartesianChart.YAxes>                       
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
CategoryAxis primaryAxis = new CategoryAxis();
chart.XAxes.Add(primaryAxis);
NumericalAxis secondaryAxis = new NumericalAxis();
chart.YAxes.Add(secondaryAxis);

this.Content = chart;

Series

Xamarin .NET MAUI
Color Fill
ColorModel, CustomBrushes PaletteBrushes
DataMarker ShowDataLabels, DataLabelSettings

The following code example explains how to migrate the series of Xamarin SfChart to .NET MAUI SfCartesianChart.

Xamarin 
<chart:SfChart>
    . . .
    <chart:ColumnSeries ItemsSource="{Binding Data}" 
                        XBindingPath="Name" 
                        YBindingPath="Height"/>
</chart:SfChart>
SfChart chart = new SfChart();
. . .

ColumnSeries series = new ColumnSeries();
series.SetBinding(ChartSeries.ItemsSourceProperty, "Data");
series.XBindingPath = "Name";
series.YBindingPath = "Height";
chart.Series.Add(series);
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
<chart:ColumnSeries ItemsSource="{Binding Data}"
					XBindingPath="Name"
					YBindingPath="Height"/>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
ColumnSeries series = new ColumnSeries();
series.ItemsSource = (new ViewModel()).Data;
series.XBindingPath = "Name";
series.YBindingPath = "Height";

chart.Series.Add(series);
this.Content = chart;

Legend

Xamarin .NET MAUI
ToggleSeriesVisibility ToggleSeriesVisibility
DockPosition Placement
IsVisible IsVisible
ItemTemplate ItemTemplate
Title Upcoming
OverflowMode Upcoming
MaxWidth Upcoming
Orientation Upcoming
IsIconVisible Upcoming
ItemMargin Upcoming
IconWidth Upcoming
IconHeight Upcoming
OffsetX Upcoming
OffsetY Upcoming

The following code example shows how to enable legend in chart.

Xamarin 
<chart:SfChart>
    <chart:SfChart.Legend>
        <chart:ChartLegend/>
    </chart:SfChart.Legend>
</chart:SfChart>
SfChart chart = new SfChart();
. . .
chart.Legend = new ChartLegend();
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
    <chart:SfCartesianChart.Legend>
	<chart:ChartLegend/>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
chart.Legend = new ChartLegend();
this.Content = chart;

Data Label

To customize the data label appearance, create an instance of the ChartDataMarker class and add it to the DataMarker of Series. For SfCartesianChart, you can set the CartesianDataLabelSettings instance to the DataLabelSettings property, as shown in the below code sample.

Xamarin 
<chart:SfChart>  
    . . .
    <chart:ColumnSeries ItemsSource="{Binding Data}" 
                        XBindingPath="Category"
                        YBindingPath="Value">
	<chart:ColumnSeries.DataMarker>
            <chart:ChartDataMarker ShowLabel="True">
	        <chart:ChartDataMarker.LabelStyle>
	    	    <chart:DataMarkerLabelStyle TextColor="Blue" 
                                            BorderColor="Red" 
                                            BorderThickness="2" 
                                            BackgroundColor="Aqua" 
                                            Angle="315" 
                                            Margin="5" FontSize="18" 
                                            FontAttributes="Italic"/>
	        </chart:ChartDataMarker.LabelStyle>
	    </chart:ChartDataMarker>
	</chart:ColumnSeries.DataMarker>
    </chart:ColumnSeries>
</chart:SfChart>
SfChart chart = new SfChart();
. . .
ColumnSeries series = new ColumnSeries();
. . .
series.DataMarker = new ChartDataMarker();
series.DataMarker.ShowLabel = true;

var style = new DataMarkerLabelStyle();
style.TextColor = Colors.Blue;
style.BorderColor = Colors.Red;
style.BorderThickness = 2;
style.BackgroundColor = Colors.Aqua;
style.Angle = 315;
style.Margin = 5;
style.FontSize = 18;
series.DataMarker.LabelStyle = style;

chart.Series.Add(series);
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
    . . .
    <chart:ColumnSeries ItemsSource="{Binding Data}" XBindingPath="Category" 
                        YBindingPath="Value" ShowDataLabels="True">
        <chart:ColumnSeries.DataLabelSettings>
            <chart:CartesianDataLabelSettings>
                <chart:CartesianDataLabelSettings.LabelStyle>
                    <chart:ChartDataLabelStyle TextColor="Blue" 
                                               Stroke="Red" 
                                               StrokeWidth="2" 
                                               Background="Aqua" 
                                               Angle="315" 
                                               Margin="5" 
                                               FontSize="18" 
                                               FontAttributes="Italic"/>
                </chart:CartesianDataLabelSettings.LabelStyle>
            </chart:CartesianDataLabelSettings>
        </chart:ColumnSeries.DataLabelSettings>  
    </chart:ColumnSeries>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
ColumnSeries series = new ColumnSeries();
. . .
series.ShowDataLabels = true;
series.CartesianDataLabelSettings = new CartesianDataLabelSettings();
var style = new ChartDataLabelStyle();
style.TextColor = Colors.Blue;
style.Stroke = Colors.Red;
style.StrokeWidth = 2;
style.Background = Colors.Aqua;
style.Angle = 315;
style.Margin = 5;
style.FontSize = 18;
series.CartesianDataLabelSettings.LabelStyle = style;

chart.Series.Add(series);
this.Content = chart;

Tooltip

To customize the tooltip appearance, create an instance of the ChartTooltipBehavior class and add it to the ChartBehaviors collection of SfChart. For SfCartesianChart, you can directly set the ChartTooltipBehavior instance to the TooltipBehavior property, as shown in the below code sample.

Xamarin 
<chart:SfChart>
    . . . 
    <chart:SfChart.ChartBehaviors>
        <chart:ChartTooltipBehavior BackgroundColor="Blue" 
                                    TextColor="White" 
                                    Margin="5" 
                                    FontSize="15"/>
    </chart:SfChart.ChartBehaviors>
    
    <chart:ColumnSeries ItemsSource="{Binding Data}" 
                        XBindingPath="Demand"
                        YBindingPath="Year2010"
                        EnableTooltip="True"/>
</chart:SfChart>
SfChart chart = new SfChart();
. . .
ColumnSeries series = new ColumnSeries();
. . .
series.EnableTooltip = true;
chart.Series.Add(series);

ChartTooltipBehavior tool = new ChartTooltipBehavior();
tool.BackgroundColor = Color.Blue;
tool.TextColor = Color.White;
tool.Margin = new Thickness(5, 5, 5, 5);
tool.FontSize = 15;
chart.ChartBehaviors.Add(tool);
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
    . . .
   <chart:SfCartesianChart.TooltipBehavior>
        <chart:ChartTooltipBehavior Background="Blue" 
                                    TextColor="White" 
                                    Margin="5" 
                                    FontSize="15"/>
   </chart:SfCartesianChart.TooltipBehavior>

   <chart:ColumnSeries ItemsSource="{Binding Data}" 
                       XBindingPath="Demand"
                       YBindingPath="Year2010"
                       EnableTooltip="True"/>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
ColumnSeries series = new ColumnSeries();
. . .
series.EnableTooltip = true;
chart.Series.Add(series);

ChartTooltipBehavior tooltip = new ChartTooltipBehavior();
tooltip.BackgroundColor = Colors.Blue;
tooltip.TextColor = Colors.White;
tooltip.Margin = new Thickness(5, 5, 5, 5);
tool.FontSize = 15;
chart.TooltipBehavior = tooltip;
this.Content = chart;

Selection

Create an instance of the ChartSelectionBehavior class and add it to the ChartBehaviors collection of SfChart. For SfCartesianChart, you can directly set the ChartSelectionBehavior instance to the SelectionBehavior property, as shown in the below code sample.

Xamarin 
<chart:SfChart>
    ...
    <chart:SfChart.ChartBehaviors>
        <chart:ChartSelectionBehavior/>
    </chart:SfChart.ChartBehaviors>

    <chart:ColumnSeries EnableDataPointSelection="True" 
                        SelectedDataPointIndex="2" 
                        SelectedDataPointColor="Red" 
                        ItemsSource ="{Binding Data}" 
                        XBindingPath="Demand" 
                        YBindingPath="Year2010"/>
</chart:SfChart>
SfChart chart = new SfChart();
. . .
ColumnSeries series = new ColumnSeries();
. . .
columnSeries.EnableDataPointSelection = true;

chart.Series.Add(series);
ChartSelectionBehavior selectionBehavior = new ChartSelectionBehavior();

chart.ChartBehaviors.Add(selectionBehavior);
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
    . . .
    <chart:SfCartesianChart.Series>
        <chart:ColumnSeries ItemsSource="{Binding Data}" 
                            XBindingPath="Name"
                            YBindingPath="Height">
            <chart:ColumnSeries.SelectionBehavior>
                <chart:DataPointSelectionBehavior SelectionBrush="#314A6E"/>
            </chart:ColumnSeries.SelectionBehavior>
        </chart:ColumnSeries>
    </chart:SfCartesianChart.Series>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
DataPointSelectionBehavior selection = new DataPointSelectionBehavior();
selection.SelectionBrush=Color.FromArgb("#314A6E");

ColumnSeries series = new ColumnSeries()
{
    ItemsSource = new ViewModel().Data,
    XBindingPath = "Name",
    YBindingPath = "Height",
    SelectionBehavior = selection
};

chart.Series.Add(series);
this.Content = chart;

NOTE

For more information about selection check here.

Zooming and Panning

The zooming and panning are achieved using the ChartZoomPanBehavior in SfChart and SfCartesianChart as shown in the below code example.

Xamarin 
<chart:SfChart>
    <chart:SfChart.ChartBehaviors>
	<chart:ChartZoomPanBehavior EnableZooming="True"/>
    </chart:SfChart.ChartBehaviors>
</chart:SfChart>
SfChart chart = new SfChart();
. . .
ChartZoomPanBehavior zoomPanBehavior = new ChartZoomPanBehavior();

chart.ChartBehaviors.Add(zoomPanBehavior);
this.Content = chart;
.NET MAUI 
<chart:SfCartesianChart>
    <chart:SfCartesianChart.ZoomPanBehavior>
        <chart:ChartZoomPanBehavior EnablePinchZooming="True"/>
    </chart:SfCartesianChart.ZoomPanBehavior>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
ChartZoomPanBehavior zooming = new ChartZoomPanBehavior();
chart.ZoomPanBehavior = zooming;
this.Content = chart;

Upcoming features in .NET MAUI

Chart

  • Suspend and resume notification support.
  • Technical indicators for charts.

Series

  • Listen to property change support for series.
  • Notify event or method when series are rendering.
  • Suspend and resume notification.
  • Trendlines support for continuous series.

Axis

  • DateTime category axis support.
  • Range style customization.
  • Event or method to notify the axis label click.
  • Support for axis draw labels as multiple lines using /n.
  • Support setting the maximum labels count for the chart axis.

Legend

  • Title support for legend.
  • Support to enable or disable the legend icon visibility.
  • Legend floating support.
  • Event or method to notify when a legend item is clicked.

Data label

  • Connector lines and its customization support.

Known issue

  • [iOS] #9135 - The chart legend was taking up a huge amount of vertical space or becoming hidden.
  • The trackball behavior is currently not supported with stacked column charts.

Unsupported features from Xamarin.Forms

  • Only continuous series will support data marker symbols.
  • Data label created event support was not provided in series. Instead, you can use the DrawDataLabel override method in the ChartSeries class.
  • OpposedPosition property was not exposed in axis. Instead, you can move to the axis opposed position by setting the CrossesAt value as double.MaxValue.
  • RangeStyle support was not provided in the axis. Instead, you can use DrawMajorTick, DrawMinorTick and DrawGridLine override methods provided in the axis class.
  • In.NET MAUI, the ChartDataPoint model class was no longer available. Instead, create your own model.

Support and feedback

If you are unable to find the migration information you require in the self-help resources listed above, please contact us by creating a support ticket. Do not see what you need? Please request it in our feedback portal.