Data Labels in .NET MAUI Circular Chart

9 Jul 202617 minutes to read

Data labels are used to display values related to a chart segment. Values from data point(x, y) or other custom properties from a data source can be displayed.

Each data label can be represented by the following:

  • Label - displays the segment label content at the (X, Y) point.
  • Connector line - used to connect the (X, Y) point and the label element.

NOTE

Prerequisite: Ensure that the required NuGet package is installed, the necessary namespaces are imported, and the SfCircularChart control is properly configured in your application. For detailed setup and configuration instructions, refer to the Getting Started guide.

Enable data labels

The ShowDataLabels property of the series is used to enable the data labels.

<chart:SfCircularChart>
    <chart:PieSeries ItemsSource="{Binding Data}"  
                     XBindingPath="Product" 
                     YBindingPath="SalesRate"
                     ShowDataLabels="True"/>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();

PieSeries series = new PieSeries()
{
    ItemsSource = new ViewModel().Data,
    XBindingPath = "Product",
    YBindingPath = "SalesRate",
    ShowDataLabels = true
};
chart.Series.Add(series);
this.Content = chart;

Data labels can be customized by using the DataLabelSettings property of the chart series. To customize the data labels, create an instance of CircularDataLabelSettings and assign it to the DataLabelSettings property. The following properties are used to customize the data labels, which are available in the CircularDataLabelSettings class:

NOTE

Data label support is applicable only for PieSeries and DoughnutSeries chart types.

Data label in .NET MAUI Circular Chart

Data label position

The LabelPosition property is used to place the data labels either Inside or Outside of the chart segment. By default, the data labels are placed inside the series.

<chart:SfCircularChart>
    <!-- code omitted for brevity -->
    <chart:PieSeries ItemsSource="{Binding Data}" 
                     XBindingPath="Product" 
                     YBindingPath="SalesRate"
                     ShowDataLabels="True">
        <chart:PieSeries.DataLabelSettings>
            <chart:CircularDataLabelSettings LabelPosition="Outside">
            </chart:CircularDataLabelSettings>
        </chart:PieSeries.DataLabelSettings>
    </chart:PieSeries>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
// code omitted for brevity
PieSeries series = new PieSeries();
series.ItemsSource = new ViewModel().Data;
series.XBindingPath = "Product";
series.YBindingPath = "SalesRate";
series.ShowDataLabels = true;

series.DataLabelSettings = new CircularDataLabelSettings()
{
    LabelPosition = ChartDataLabelPosition.Outside
};

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

Smart labels

The SmartLabelAlignment property is used to arrange the data labels smartly to avoid intersection when labels overlap. The SmartLabelAlignment enum contains the following values:

  • Shift - Smartly arranges the overlapped data labels.
  • Hide - Hides the intersected data labels.
  • None - Keeps the intersected data labels visible.

By default, the value for the SmartLabelAlignment property is Shift.

If the LabelPosition is Inside and the SmartLabelAlignment is Shift, then the overlapped labels will shift to outside the slices and arrange smartly. If the LabelPosition is Inside and the SmartLabelAlignment is Hide, then the overlapped labels will be hidden.

If the LabelPosition is Outside and the SmartLabelAlignment is Shift, then the overlapped labels arrange smartly. If the LabelPosition is Outside and the SmartLabelAlignment is Hide, then the overlapped labels will be hidden.

If the SmartLabelAlignment is None, then the overlapped labels will be visible irrespective of LabelPosition.

When the SmartLabelAlignment is Shift, and if the data label goes out of the chart area, then the labels are trimmed.

<chart:SfCircularChart>
    <chart:PieSeries ItemsSource="{Binding Data}"
                     XBindingPath="Product" 
                     YBindingPath="SalesRate"
                     ShowDataLabels="True">
        <chart:PieSeries.DataLabelSettings>
            <chart:CircularDataLabelSettings LabelPosition="Outside" SmartLabelAlignment="Shift">
            </chart:CircularDataLabelSettings>
        </chart:PieSeries.DataLabelSettings>
    </chart:PieSeries>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
// code omitted for brevity
PieSeries series = new PieSeries();
series.ItemsSource = new ViewModel().Data;
series.XBindingPath = "Product";
series.YBindingPath = "SalesRate";
series.ShowDataLabels = true;

series.DataLabelSettings = new CircularDataLabelSettings()
{
    LabelPosition = ChartDataLabelPosition.Outside,
    SmartLabelAlignment = SmartLabelAlignment.Shift
};

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

Smart Labels in .NET MAUI Circular Chart

Applying series brush

The UseSeriesPalette property is used to set the interior of the series to the data label background. By default, its value is false.

<chart:SfCircularChart>
    <!-- code omitted for brevity -->
    <chart:PieSeries ItemsSource="{Binding Data}"
                     XBindingPath="Product"
                     YBindingPath="SalesRate"
                     ShowDataLabels="True">
        <chart:PieSeries.DataLabelSettings>
            <chart:CircularDataLabelSettings UseSeriesPalette="True"/>
        </chart:PieSeries.DataLabelSettings>
    </chart:PieSeries>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
// code omitted for brevity
PieSeries series = new PieSeries()
{
    ItemsSource = new ViewModel().Data,
    XBindingPath = "Product",
    YBindingPath = "SalesRate",
    ShowDataLabels = true
};
series.DataLabelSettings = new CircularDataLabelSettings()
{
    UseSeriesPalette = true
};

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

Applying series interior for data label in .NET MAUI Circular Chart

Formatting label context

The content of the label can be customized using the LabelContext property of the series. The following two options are supported:

  • Percentage - Displays the percentage value of the corresponding data point Y value.
  • YValue - Displays the corresponding Y value.

By default, the value for the LabelContext property is YValue.

<chart:SfCircularChart>
    <!-- code omitted for brevity -->
    <chart:PieSeries ItemsSource="{Binding Data}" 
                     XBindingPath="Product" 
                     YBindingPath="SalesRate"
                     ShowDataLabels="True"
                     LabelContext="Percentage"/>  
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
// code omitted for brevity
PieSeries series = new PieSeries()
{
    ItemsSource = new ViewModel().Data,
    XBindingPath = "Product",
    YBindingPath = "SalesRate",
    ShowDataLabels = true,
    LabelContext = LabelContext.Percentage
};

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

DataLabel context in .NET MAUI Circular Chart

Label template

The SfCircularChart provides support to customize the appearance of the data labels using the LabelTemplate property of the series. The binding context of the label template is Item, which exposes the underlying data object’s properties.

<chart:SfCircularChart>

    <chart:SfCircularChart.Resources>
        <DataTemplate x:Key="labelTemplate">
            <HorizontalStackLayout Spacing="5">
                <Label Text="{Binding Item.Product}" TextColor="White" FontSize="13"/>
                <Label Text=" : " TextColor="White" FontSize="13"/>
                <Label Text="{Binding Item.SalesRate}" TextColor="White" FontSize="13"/>
            </HorizontalStackLayout>
        </DataTemplate>
    </chart:SfCircularChart.Resources>

    <chart:PieSeries ItemsSource="{Binding Data}"
                     XBindingPath="Product" 
                     YBindingPath="SalesRate" 
                     ShowDataLabels="True"
                     LabelTemplate="{StaticResource labelTemplate}">
    </chart:PieSeries>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
// code omitted for brevity
PieSeries series = new PieSeries();
series.ItemsSource = new ViewModel().Data;
series.XBindingPath = "Product";
series.YBindingPath = "SalesRate";
series.ShowDataLabels = true;

DataTemplate labelTemplate = new DataTemplate(() =>
{
    var horizontalStackLayout = new HorizontalStackLayout { Spacing = 5 };

    var productLabel = new Label
    {
        TextColor = Colors.White,
        FontSize = 13
    };
    productLabel.SetBinding(Label.TextProperty, "Item.Product");

    var separatorLabel = new Label
    {
        Text = " : ",
        TextColor = Colors.White,
        FontSize = 13
    };

    var salesRateLabel = new Label
    {
        TextColor = Colors.White,
        FontSize = 13
    };
    salesRateLabel.SetBinding(Label.TextProperty, "Item.SalesRate");

    horizontalStackLayout.Add(productLabel);
    horizontalStackLayout.Add(separatorLabel);
    horizontalStackLayout.Add(salesRateLabel);

    return horizontalStackLayout;
});

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

Label template in .NET MAUI Circular Chart

Connector line style

The ConnectorLineStyle is used to customize the appearance of the line that connects data labels positioned outside the chart series. The connector line is drawn only when the LabelPosition is set to Outside. The following properties of the ConnectorLineStyle class are used to customize the connector line:

  • Stroke, of type Brush, specifies the stroke color of the connector line.
  • StrokeWidth, of type double, specifies the stroke thickness of the connector line.
  • StrokeDashArray, of type DoubleCollection, specifies the dashes for the connector line.
  • ConnectorType, of type ConnectorType, specifies the connector type. The ConnectorType enum contains the following values:
    • Line - Draws a straight connector line (default).
    • Curve - Draws a curved (Bezier) connector line.

By default, the value for the ConnectorType property is Line.

<chart:SfCircularChart>
    <chart:SfCircularChart.Resources>
        <DoubleCollection x:Key="dashArray">
            <x:Double>5</x:Double>
            <x:Double>2</x:Double>
        </DoubleCollection>
    </chart:SfCircularChart.Resources>
    <chart:PieSeries ItemsSource ="{Binding Data}" 
                     XBindingPath="XValue" 
                     YBindingPath="YValue"
                     ShowDataLabels="True">
        <chart:PieSeries.DataLabelSettings>
            <chart:CircularDataLabelSettings LabelPosition="Outside">
                <chart:CircularDataLabelSettings.ConnectorLineSettings>
                    <chart:ConnectorLineStyle StrokeDashArray="{StaticResource dashArray}" 
                                              ConnectorType="Curve" 
                                              Stroke="Black" 
                                              StrokeWidth="3"/>
                </chart:CircularDataLabelSettings.ConnectorLineSettings>
            </chart:CircularDataLabelSettings>
        </chart:PieSeries.DataLabelSettings>
    </chart:PieSeries>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
DoubleCollection doubleCollection = new DoubleCollection();
doubleCollection.Add(5);
doubleCollection.Add(2);
// code omitted for brevity
PieSeries series = new PieSeries()
{
    ItemsSource = new ViewModel().Data,
    XBindingPath = "XValue",
    YBindingPath = "YValue",
    ShowDataLabels = true
};

var connectorLineStyle = new ConnectorLineStyle
{
    StrokeDashArray = doubleCollection,
    ConnectorType = ConnectorType.Curve,
    Stroke = new SolidColorBrush(Colors.Black),
    StrokeWidth = 3
};
series.DataLabelSettings = new CircularDataLabelSettings()
{
    LabelPosition = ChartDataLabelPosition.Outside,
    ConnectorLineSettings = connectorLineStyle
};

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

Connector line style in .NET MAUI Circular Chart