Legend in WinUI Charts (SfChart)

31 May 202220 minutes to read

Legend provides metadata that helps in identifying elements in chart like chart series.
You can define the legend using the following code example.

<chart:SfChart.Legend>

       <chart:ChartLegend />                                 

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

chart.Legend = new ChartLegend();

Legend support in WinUI Chart

Legend Header

WinUI Charts provides support to add any UIElement as a header for legend items.

You can define the Header for legend using the following code example.

<chart:SfChart.Legend>

      <chart:ChartLegend>

          <chart:ChartLegend.Header>

               <TextBlock Text="Medals" VerticalAlignment="Center"  

                           HorizontalAlignment="Center" Margin="15"/>

            </chart:ChartLegend.Header>

     </chart:ChartLegend>

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

TextBlock textBlock = new TextBlock()
{

    Text = "Medals",

    HorizontalAlignment = HorizontalAlignment.Center,

    VerticalAlignment = VerticalAlignment.Center,

    Margin = new Thickness(15)

};

legend.Header = textBlock;

chart.Legend = legend;

Legend header in WinUI Chart

Legend Icon

Represents the symbol associated with each legend item. By default, the legend icon is Rectangle. This can be customized using the LegendIcon property in any series, as shown in the following code sample.

<chart:SfChart.Legend>

      <chart:ChartLegend/>

</chart:ChartLegend>

<chart:SplineSeries XBindingPath="Year" Label="Gold" ItemsSource="{Binding List}" 

YBindingPath="India" LegendIcon="Diamond" />
chart.Legend = new ChartLegend();

SplineSeries splineSeries = new SplineSeries()
{

    Label = "Gold",

    ItemsSource = new ViewModel().List,

    XBindingPath = "Year",

    YBindingPath = "India",

    LegendIcon = ChartLegendIcon.Diamond

};

chart.Series.Add(splineSeries);

Legend icon in WinUI Chart

The following properties are used to customize the legend:

  • 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.
  • ItemMargin - Gets or sets the margin for the legend items.
  • CornerRadius - Gets or sets the corner radius of the legend.

The following code example illustrates the customization of legend.

<chart:SfChart.Legend>

    <chart:ChartLegend  IconHeight="10" IconWidth="10" 

                        Margin="0,0,0,5"

                        HorizontalAlignment="Center"

                        VerticalAlignment="Center"                                    

                        DockPosition="Top"

                        BorderBrush="Black" BorderThickness="1"

                        IconVisibility="Visible" CornerRadius="5"

                        ItemMargin="10">                   

    </chart:ChartLegend>

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

    IconHeight = 10,

    IconWidth = 10,

    Margin = new Thickness(0, 0, 0, 5),

    HorizontalAlignment = HorizontalAlignment.Center,

    VerticalAlignment = VerticalAlignment.Center,

    DockPosition = ChartDock.Top,

    IconVisibility = Visibility.Visible,

    CornerRadius = CornerRadiusHelper.FromUniformRadius(5),

    ItemMargin = new Thickness(10),

    BorderThickness = new Thickness(1),

    BorderBrush = new SolidColorBrush(Colors.Black)

};

Legend customization in WinUI Chart

The visibility of the legend icon can be changed by setting the IconVisibility property in ChartLegend.

<chart:SfChart.Legend>

   <chart:ChartLegend  IconHeight="8" IconWidth="8"  

                       IconVisibility="Collapsed" />                                 

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

    IconHeight = 8,

    IconWidth = 8,

    IconVisibility = Visibility.Collapsed,

};

Legend icon visibility support in WinUI Chart

Custom Legend Icon

You can add custom icon for the legend using the LegendIconTemplate property in ChartSeries as shown in the following code example.

<syncfusion:SfChart x:Name="chart">

    <syncfusion:SfChart.Resources>

        <DataTemplate x:Key="iconTemplate">

            <Ellipse Height="15" Width="15" Fill="White" 
			                   
                     Stroke="#4a4a4a" StrokeThickness="2"/>

        </DataTemplate>

    </syncfusion:SfChart.Resources>

    <syncfusion:SfChart.Legend>

        <syncfusion:ChartLegend/>

     </syncfusion:SfChart.Legend>

    <syncfusion:SplineSeries XBindingPath="Year"  Label="Gold" 
  
	                         ItemsSource="{Binding List}" 
                                     
                             YBindingPath="India" 
                                     
                             IconTemplate="{StaticResource iconTemplate}">

    </syncfusion:SplineSeries>
        
</syncfusion:SfChart>
SplineSeries series = new SplineSeries()
{

    ItemsSource = new ViewModel().List,

    XBindingPath = "Year",

    YBindingPath = "India",

    IconTemplate = chart.Resources["iconTemplate"] as DataTemplate

};

chart.Series.Add(series);

Customizing legend icons in WinUI Chart

Legend Label

This allows you to specify the label for each series that will be displayed in the legend label.

<chart:SfChart.Legend>

    <chart:ChartLegend>

    </chart:ChartLegend>

</chart:SfChart.Legend>

<chart:SplineSeries XBindingPath="Year" Label="Spline"
   
	                  ItemsSource="{Binding List}" YBindingPath="India"/>
chart.Legend = new ChartLegend();

SplineSeries splineSeries = new SplineSeries()
{

    Label = "Spline",

    ItemsSource = new ViewModel().List,

    XBindingPath = "Year",

    YBindingPath = "India",

};

chart.Series.Add(splineSeries);

Labels for legend in WinUI Chart

Checkbox for Legend

Checkbox for legend is used to view or collapse the associated series. By default, the CheckboxVisibility is Collapsed.

You can enable it by using the CheckBoxVisibility property as shown in the following code example.

<chart:SfChart.Legend>

        <chart:ChartLegend CheckBoxVisibility="Visible" />

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

    CheckBoxVisibility = Visibility.Visible

};

Checkbox support for legend in WinUI Chart

The series can be collapsed by unchecking the checkbox as follows.

Checkbox support for legend in WinUI Chart

ToggleSeriesVisibility

ToggleSeriesVisibility is used to view or collapse the associated series, by clicking on its legend item. By default, ToggleSeriesVisibility property is False.

You can enable the ToggleSeriesVisibility property as shown in the following code example.

<chart:SfChart.Legend>

        <chart:ChartLegend ToggleSeriesVisibility="True" />

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

    ToggleSeriesVisibility = true

};

The series can be collapsed, by clicking on the respective legend item,

ToggleSeriesVisibility support for legend in WinUI Chart

You can also view the associated series, by clicking on its disabled legend item.

ToggleSeriesVisibility support for legend in WinUI Chart

Positioning the Legend

Legend Position

This allows you to position the legends Inside or Outside of the chart area (plotting area).
By default, it will be displayed outside and positioned at top (using DockPosition) of the chart area.

<chart:SfChart.Legend>

     <chart:ChartLegend Position="Inside" />                                 

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

    Position = LegendPosition.Inside

};

Positioning the legend at inside in WinUI Chart

Docking

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

To display the legend at the bottom, you can set the DockPosition as Bottom as shown in the following code sample.

<chart:SfChart.Legend>

    <chart:ChartLegend  DockPosition="Bottom"/>

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

    DockPosition = ChartDock.Bottom

};

Positioning the legend at bottom in WinUI Chart

Floating Legends

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

Offset specifies x or y distance from origin.

<chart:SfChart.Legend>

      <chart:ChartLegend  DockPosition="Floating" OffsetX="30" OffsetY="10"/>

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

    DockPosition = ChartDock.Floating,

    OffsetX = 30,

    OffsetY = 10

};

Positioning the floating legend support in WinUI Chart

Legends for Accumulation Series

For the series like Pie, Doughnut, Funnel and Pyramid, legends will be generated for all the data points. But for the remaining series, each legend corresponds to each series. By default, the Interior color of the segment (data point) is applied to the legend icon.

The following code sample explains how the legends display for the accumulation series.

<chart:SfChart.Legend>

   <chart:ChartLegend />                                 

</chart:SfChart.Legend>

<chart:PieSeries  XBindingPath="Category" 
	
	             ItemsSource="{Binding Tax}" YBindingPath="Percentage"/>
chart.Legend = new ChartLegend();

PieSeries pieSeries = new PieSeries()
{

    ItemsSource = new ViewModel().Tax,

    XBindingPath = "Category",

    YBindingPath = "Percentage"

};

chart.Series.Add(pieSeries);

Legends for circular series in WinUI Chart

NOTE

Here, Legend ‘Label’ will be the x value of the Pie chart.

Series Visibility on Legend

You can limit the number of series and trendlines to be displayed in the chart using the VisibilityOnLegend
property as shown in the following code example.

<chart:SfChart.Legend>

    <chart:ChartLegend>                  

    </chart:ChartLegend>

</chart:SfChart.Legend>

<chart:SplineSeries XBindingPath="Year" Label="Gold" 

                    VisibilityOnLegend="Collapsed"

                    ItemsSource="{Binding List}" YBindingPath="India">

</chart:SplineSeries>

<chart:ColumnSeries XBindingPath="Year"

                    VisibilityOnLegend="Visible"

                    Label="Silver" YBindingPath="America"

                    ItemsSource="{Binding List}" />
chart.Legend = new ChartLegend();

SplineSeries splineSeries = new SplineSeries()
{

    Label = "Gold",

    ItemsSource = new ViewModel().List,

    XBindingPath = "Year",

    YBindingPath = "India",

    VisibilityOnLegend = Visibility.Collapsed

};

ColumnSeries columnSeries = new ColumnSeries()
{

    Label = "Silver",

    ItemsSource = new ViewModel().List,

    XBindingPath = "Year",

    YBindingPath = "America",

    VisibilityOnLegend = Visibility.Visible

};

chart.Series.Add(splineSeries);

chart.Series.Add(columnSeries);

Series visibility of legend in WinUI Chart

Legend Orientation

Orientation of the legend can be vertical or horizontal. By default, the Orientation is Horizontal.

<chart:SfChart.Legend>

   <chart:ChartLegend  Orientation="Vertical"/>

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

    Orientation = ChartOrientation.Vertical

};

Legend orientation support in WinUI Chart

Customization

ItemTemplate

You can customize each legend item using the ItemTemplate property in ChartLegend as shown in the following code sample.

<syncfusion:SfChart x:Name="chart">

     <syncfusion:SfChart.Resources>

            <local:ImageConverter x:Key="imageConverter"/>

            <DataTemplate x:Key="itemTemplate">

                <Grid Margin="10,0,10,0" >

                    <Grid.RowDefinitions>

                        <RowDefinition/>

                        <RowDefinition/>

                    </Grid.RowDefinitions>

                    <Image  Width="30" Height="15"
                                        
                            Source="{Binding Converter={StaticResource imageConverter}}"/>

                    <TextBlock HorizontalAlignment="Center" FontSize="12"
                                           
                               Grid.Row="1" Foreground="Black" 
                                           
                               FontWeight="SemiBold" Text="{Binding Label}">

                    </TextBlock>

                </Grid>

             </DataTemplate>

    </syncfusion:SfChart.Resources>

    <syncfusion:SfChart.Legend>

                <syncfusion:ChartLegend ItemTemplate="{StaticResource itemTemplate}"/>

    </syncfusion:SfChart.Legend>

</syncfusion:SfChart>
SfChart chart = new SfChart();

chart.Legend = new ChartLegend()
{

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

};

public class ImageConverter:IValueConverter

{

 public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)

  {

   LegendItem item = value as LegendItem;

   if (item.Label == "Gold")

     return new BitmapImage(new Uri(("gold_symb.png"),UriKind.RelativeOrAbsolute));

   else

    return new BitmapImage(new Uri(("silver_symb.png"), UriKind.RelativeOrAbsolute));

  }

  public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)

  {

    return value;

  }

}

Item template support for legend in WinUI Chart