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 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 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);
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)
};
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,
};
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);
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);
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
};
The series can be collapsed by unchecking the checkbox as follows.
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,
You can also view the associated series
, by clicking on its disabled legend item.
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
};
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
};
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
};
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);
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);
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
};
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;
}
}