Legend in WinUI Charts (SfCircularChart)

7 Jul 202113 minutes to read

The legend contains list of series data points in the chart. The information provided in each legend item helps to identify the corresponding data series in the chart.

<chart:SfCircularChart.Legend>
    <chart:ChartLegend/>
</chart:SfCircularChart.Legend>
SfCircularChart chart = new SfCircularChart();
chart.Legend = new ChartLegend();

NOTE

The x-value of data points in the circular chart will be the legend items ‘Label’.

Legend support in WinUI Pie Chart

Title

Circular chart provides support to add any UIElement as a title for legend. Header property of ChartLegend is used to define the title for legend as the following code example.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend>
            <chart:ChartLegend.Header>
                <TextBox Text="Products" 
                         HorizontalAlignment="Center"
                         FontWeight="Bold"
                         Foreground="Blue"/>
            </chart:ChartLegend.Header>
    </chart:ChartLegend>
</chart:SfCircularChart.Legend>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
ChartLegend legend = new ChartLegend();

TextBlock textBlock = new TextBlock()
{
    Text = "Products",
    HorizontalTextAlignment = TextAlignment.Center,
    Foreground = new SolidColorBrush(Colors.Blue),
    FontWeight = FontWeights.Bold,
};

legend.Header = textBlock;
chart.Legend = legend;

Legend header in WinUI Pie Chart

Icon

Legend icon represents a symbol associated with the each legend item. LegendIcon property of series is used to set the icon type for legend item. By default, the legend icon is SeriesType.

<chart:SfCircularChart>
. . .
<chart:SfCircularChart.Legend>
    <chart:ChartLegend/>
</chart:SfCircularChart.Legend>


<chart:SfCircularChart.Series>
    <chart:PieSeries LegendIcon="Rectangle"
                     ItemsSource="{Binding Data}"  
                     XBindingPath="Product" 
                     YBindingPath="SalesRate">
    </chart:PieSeries>
</chart:SfCircularChart.Series>
. . .
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend();

PieSeries series = new PieSeries();
series.LegendIcon = ChartLegendIcon.Circle;

chart.Series.Add(series);

Legend icon in WinUI Pie Chart

The appearance of the legend icon can be customized using the below properties.

  • IconWidth - Gets or sets the double value that represents the legend icon(s) width.
  • IconHeight - Gets or sets the double value that represents that legend icon(s) height.
  • IconVisibility - Gets or sets the Visibility of the legend icon.
<chart:SfCircularChart>
. . .
<chart:SfCircularChart.Legend>
    <chart:ChartLegend IconWidth="10" IconHeight="5" 
                       IconVisibility="Visible">
    </chart:ChartLegend>
</chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    IconWidth = 10,
    IconHeight = 5,
    IconVisibility = Visibility.Visible,
};

Custom legend icon

Circular chart provides support to add custom icon for the legend using LegendIconTemplate property of series as in below example.

<chart:SfCircularChart>
    <chart:SfCircularChart.Resources>
        <DataTemplate x:Key="iconTemplate">
            <Ellipse Height="15" Width="15" Fill="White" 
                 Stroke="#4a4a4a" StrokeThickness="2"/>
        </DataTemplate>
    </chart:SfCircularChart.Resources>

    <chart:SfCircularChart.Legend>
        <chart:ChartLegend IconWidth="15" IconHeight="15"/>
    </chart:SfCircularChart.Legend>
    
    <chart:PieSeries 
        LegendIconTemplate="{StaticResource iconTemplate}"
        ItemsSource="{Binding Data}"/>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
PieSeries series = new PieSeries();
series.LegendIconTemplate = chart.Resources["iconTemplate"] as DataTemplate;
. . .
chart.Series.Add(series);

Customizing legend icons in WinUI Pie Chart

Item spacing

ItemMargin property of the ChartLegend is used to provide spacing between each legend items.

<chart:SfCircularChart>
. . .
<chart:SfCircularChart.Legend>
    <chart:ChartLegend ItemMargin="10"/>
</chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    ItemMargin = new Thickness(10)
};

Legend item spacing support in WinUI Pie Chart

Checkbox for Legend

Circular chart provides support to enable the checkbox for each legend item to visible or collapse the associated data points. By default, the value of CheckBoxVisibility property is Collapsed.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend CheckBoxVisibility="Visible"/>
    </chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
   CheckBoxVisibility = Visibility.Visible
};

Checkbox support for legend in WinUI Pie Chart

The data point can be collapsed by unchecking the checkbox as below:

Checkbox support for legend in WinUI Pie Chart

Toggle series visibility

The visibility of the segment can be control by tapping the legend item by enabling the ToggleSeriesVisibility property. By default, the value of ToggleSeriesVisibility property is False.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend ToggleSeriesVisibility="True"/>
    </chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
   ToggleSeriesVisibility = true
};

ToggleSeriesVisibility support for legend in WinUI Pie Chart

Position

The legends can be placed either inside or outside of the chart area (plotting area). By default, it will be displayed outside and positioned at top (using Position) of the chart area.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend Position="Inside"/>
    </chart:SfCircularChart.Legend>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    Position = LegendPosition.Inside
};

Docking

Legends can be docked left, right, and top or bottom around the chart area using DockPosition property. By default, the chart legend is docked at the top of the chart as mentioned earlier.

To display the legend at the left, set the DockPosition as Left as in below code snippet.

<chart:SfCircularChart>
. . .
<chart:SfCircularChart.Legend>
    <chart:ChartLegend ItemMargin="10" DockPosition="Left"/>
</chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
   DockPosition = ChartDock.Left
};

Positioning the legend at left in WinUI Pie Chart

Floating legends

To position the legend at any arbitrary location inside chart, need to set DockPosition as Floating and provide its relative position by using OffsetX and OffsetY properties.

Offset specifies x or y distance from origin.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend DockPosition="Floating" OffsetX="330" OffsetY="160"/>
    </chart:SfCircularChart.Legend>
</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    DockPosition = ChartDock.Floating,
    OffsetX = 330,
    OffsetY = 160
};

Positioning the legend at floating in WinUI Pie Chart

Orientation

Orientation of the legend items can aligned vertically or horizontally by setting Orientation property of legend. By default, the value of Orientation property is Horizontal.

<chart:SfCircularChart>
. . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend Orientation="Vertical"/>
    </chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    Orientation = ChartOrientation.Vertical
};

Legend orientation support in WinUI Pie Chart

Background Customization

The legend background appearance can be customized by using the below properties.

BorderThickness - used to change the stroke width of the legend.
BorderBrush - used to change the stroke color of the legend.
Background - used to change the background color of legend.
Opacity - used to control the transparency of the legend icon shape.
CornerRadius - used to change the corner radius of the legend.

<chart:SfCircularChart>
. . .
<chart:SfCircularChart.Legend>
    <chart:ChartLegend Background="Gray" BorderBrush="Black" 
                       BorderThickness="1" CornerRadius="5" 
                       Opacity="0.9" >
    </chart:ChartLegend>
</chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{
    Background = new SolidColorBrush(Colors.Gray),
    BorderBrush = new SolidColorBrush(Colors.Black),
    BorderThickness = new Thickness(1),
    Opacity = 0.9,
    CornerRadius = CornerRadiusHelper.FromUniformRadius(5)
};

Template

Customize each legend item by using ItemTemplate property in ChartLegend as in below code snippet:

<chart:SfCircularChart>
    <chart:SfCircularChart.Resources>
        <DataTemplate x:Key="labelTemplate">
            <StackPanel Margin="10" Orientation="Vertical">
                <Ellipse Height="15" Width="15" Fill="{Binding Interior}" 
                 Stroke="#4a4a4a" StrokeThickness="2"/>
                <TextBlock HorizontalAlignment="Center" FontSize="12"
                           Foreground="Black" 
                           FontWeight="SemiBold" Text="{Binding Label}"/>
            </StackPanel>
        </DataTemplate>
    </chart:SfCircularChart.Resources>
    . . .
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend ItemTemplate="{StaticResource labelTemplate}"/>
    </chart:SfCircularChart.Legend>

</chart:SfCircularChart>
SfCircularChart chart = new SfCircularChart();
. . .
chart.Legend = new ChartLegend()
{

   ItemTemplate = chart.Resources["itemTemplate"] as DataTemplate
};

Item template support for legend in WinUI Pie Chart