Legend in Xamarin Charts (SfChart)

17 Oct 202317 minutes to read

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

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

<chart:SfChart>

	<chart:SfChart.Legend>

		<chart:ChartLegend/>

	</chart:SfChart.Legend>

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

Legend support in Xamarin.Forms Chart

Customizing background & border

The Legend provides following properties to customize the legend area border and background.

  • BackgroundColor - used to change legend background color.
  • StrokeColor - used to change legend border color.
  • StrokeWidth - used to change legend border width
  • StrokeDashArray - used to render legend border line with dashes.
  • Margin - used to change legend panel margin with legend border.
  • CornerRadius - used to add the rounded corners to the legend border rectangle. The TopLeft, TopRight, BottomLeft and BottomRight of ChartCornerRadius properties are used to set the radius value for each corner.
xmlns:sys="clr-namespace:System;assembly=mscorlib" 
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"  
xmlns:chart="clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms" 

...  

<chart:SfChart>

	<chart:SfChart.Legend>

		 <chart:ChartLegend StrokeColor="Black" CornerRadius="5" StrokeWidth="2"
                                    BackgroundColor="#f5f5f0" Margin="5">

                        <chart:ChartLegend.StrokeDashArray>
                            <x:Array Type="{x:Type sys:Double}">
                                <sys:Double>3</sys:Double>
                                <sys:Double>3</sys:Double>
                            </x:Array>
                        </chart:ChartLegend.StrokeDashArray>

                    </chart:ChartLegend>

	</chart:SfChart.Legend>

</chart:SfChart>
ChartLegend legend = new ChartLegend();
 legend.BackgroundColor = Color.FromRgb(245, 245, 240);
 legend.Stroke = Color.Black;
 legend.StrokeWidth = 2;
 legend.Margin = new Thickness(5);
 legend.CornerRadius = new ChartCornerRadius(5);
 legend.StrokeDashArray = new double[] { 3, 3 };

 chart.Legend = legend;

Legend background and border customization in Xamarin.Forms Chart

Customizing labels

The Label property of ChartSeries is used to define the label for the corresponding series legend item. The appearance of the label can be customized using the LabelStyle property.

  • TextColor – used to change the color of the label.
  • Font – used to change the text size, font family, and font weight. (This is deprecated API. Use FontSize, FontFamily, and FontAttributes properties instead of this.)
  • FontFamily - used to change the font family for the legend label.
  • FontAttributes - used to change the font style for the legend label.
  • FontSize - used to change the font size for the legend label.
  • Margin - used to change the margin size of labels.
<chart:SfChart.Legend>

	<chart:ChartLegend>

		<chart:ChartLegend.LabelStyle>

			<chart:ChartLegendLabelStyle TextColor="Blue" Margin="5" FontSize="18" FontAttributes="Bold"/>

		</chart:ChartLegend.LabelStyle>

	</chart:ChartLegend>

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

chart.Legend.LabelStyle.TextColor = Color.Blue;

chart.Legend.LabelStyle.FontSize = 18;

chart.Legend.LabelStyle.FontAttributes = FontAttributes.Bold;

chart.Legend.LabelStyle.Margin = 5;

Legend labels customization support in Xamarin.Forms Chart

Legend icons

The legend icons are enabled by default. However, you can control its visibility using the IsIconVisible property. The icon type also can be specified using the LegendIcon property such as Rectangle, Circle and Diamond, etc., The IconWidth and IconHeight properties are used to adjust the width and height of the legend icons, respectively.

<chart:SfChart>

	<chart:SfChart.Legend>

		<chart:ChartLegend IsIconVisible="True" IconHeight="20" IconWidth="20"/>

	</chart:SfChart.Legend>

	<chart:PieSeries ItemsSource ="{Binding Data1}" LegendIcon="SeriesType"/>

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

chart.Legend.IconHeight = 20;

chart.Legend.IconWidth = 20;

chart.Legend.IsIconVisible = true;

pieSeries.LegendIcon = ChartLegendIcon.SeriesType;

Legend icons in Xamarin.Forms Chart

Legend title

The following properties are used to define and customize the Title of legend.

  • Text – used to change the text of the title.
  • TextColor – used to change the color of the title text.
  • Font – used to change the text size, font family, and font weight. (This is deprecated API. Use FontSize, FontFamily, and FontAttributes properties instead of this.)
  • FontFamily - used to change the font family for the legend label.
  • FontAttributes - used to change the font style for the legend label.
  • FontSize - used to change the font size for the legend label.
  • Margin – used to change the margin size of title.
  • TextAlignment – used to change the alignment of the title text; it can be start, end, or center.
  • BackgroundColor – used to change the title background color.
  • BorderColor – used to change the border color.
  • BorderWidth – used to adjust the border width of title.
<chart:SfChart.Legend>

	<chart:ChartLegend>

		<chart:ChartLegend.Title >

			<chart:ChartTitle Text="Years" TextColor="Maroon" TextAlignment="Center" 
							  BackgroundColor="Silver" BorderWidth="3" BorderColor="Blue" FontSize="20"
                                        FontAttributes="Bold"/>

			</chart:ChartTitle>

		</chart:ChartLegend.Title>

	</chart:ChartLegend>

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

chart.Legend.Title.Text = "Year";

chart.Legend.Title.TextColor = Color.Maroon;

chart.Legend.Title.FontSize = 20;

chart.Legend.Title.FontAttributes = FontAttributes.Bold;

chart.Legend.Title.TextAlignment = TextAlignment.Center;

chart.Legend.Title.BackgroundColor = Color.Silver;

chart.Legend.Title.BorderWidth = 3;

chart.Legend.Title.BorderColor = Color.Blue;

Title for legend in Xamarin.Forms Chart

Toggle the series visibility

You can control the visibility of the series by tapping the legend item. You can enable this feature by enabling the ToggleSeriesVisibility property.

<chart:SfChart>

	<chart:SfChart.Legend>

		<chart:ChartLegend ToggleSeriesVisibility="True"/>

	</chart:SfChart.Legend>

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

chart.Legend.ToggleSeriesVisibility = true;

Legend visibility

The IsVisible property of ChartLegend is used to toggle the visibility of legend.

<chart:SfChart>

	<chart:SfChart.Legend>

		<chart:ChartLegend IsVisible="False"/>

	</chart:SfChart.Legend>

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

chart.Legend.IsVisible = false;

Legend item visibility

You can control the visibility of a particular series’ legend item using the IsVisibleOnLegend property of series. The default value of the IsVisibleOnLegend property is true.

<chart:ColumnSeries ItemsSource="{Binding ColumnData}" XBindingPath="Name" 
				YBindingPath="Value" IsVisibleOnLegend="true" > 
</chart:ColumnSeries>
ColumnSeries column = new ColumnSeries();

column.XBindingPath = "Name";

column.YBindingPath = "Value";

column.ItemsSource = viewModel.ColumnData;

column.IsVisibleOnLegend = true;

Item margin

The ItemMargin property is used to set the spacing between the legend items.

<chart:SfChart.Legend>

    <chart:ChartLegend ItemMargin="20"/>

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

chart.Legend.ItemMargin = 20;

Spacing support between legend items in Xamarin.Forms Chart

Legend wrap

The legend items can be placed in multiple rows using the OverflowMode property if size of the total legend exceeds the available size. The default value of the OverflowMode property is Scroll.

<chart:SfChart.Legend>

    <chart:ChartLegend OverflowMode="Wrap"/>

</chart:SfChart.Legend>
chart.Legend = new ChartLegend()
{
    OverflowMode = ChartLegendOverflowMode.Wrap
};

Legend wrapping support in Xamarin.Forms Chart

Legend width

The legend width can be specified using the MaxWidth property. This property works only when the OverflowMode is Wrap. The default value of the MaxWidth property is double.NAN.

<chart:SfChart>

    <chart:SfChart.Legend>

        <chart:ChartLegend OverflowMode = “Wrap”  MaxWidth = “750” />

    </chart:SfChart.Legend>

</chart:SfChart>
chart.Legend = new ChartLegend()
{
    OverflowMode = ChartLegendOverflowMode.Wrap,

    MaxWidth = 750
};

Providing width for legend in Xamarin.Forms Chart

Positioning the legend

You can position the legend anywhere inside the chart. The following properties are used to customize the position of legend:

  • DockPosition – used to position the legend relatively. The available options are Left, Right, Top, Bottom, and Floating. If the DockPosition is Floating, you can position the legend using the x and y-coordinates.
  • OffsetX – used to move the legend on x-coordinate by the given offset value.
  • OffsetY - used to move the legend on y-coordinate by the given offset value.
  • Orientation - used to change the orientation of the legend, the default value is Auto, orientation of the legend items will be changed based on its dock position. Also, you can manually set Horizontal or Vertical.
<chart:SfChart>

	<chart:SfChart.Legend>

		<chart:ChartLegend DockPosition="Floating" OffsetX="70" OffsetY="90" 
						   Orientation="Vertical">        

	</chart:SfChart.Legend>           

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

chart.Legend.DockPosition = LegendPlacement.Floating;

chart.Legend.Orientation = ChartOrientation.Vertical;

chart.Legend.OffsetX = 70;

chart.Legend.OffsetY = 90;

Legend positioning support in Xamarin.Forms Chart

Populate the data based legend items for all series

The Series property of ChartLegend is used to populate the legend items based on the data points which are present in the assigned series.

The following code example shows how to enable datapoint-based legend for Cartesian series.

<chart:SfChart>

…

<chart:ChartLegend x:Name="chartLegend" Series="{Binding Source={ x:Reference Series}}" />

…

<chart:SfChart.Series>
                <chart:ColumnSeries x:Name="Series"    ItemsSource="{Binding CategoryData}" XBindingPath="Name" YBindingPath="Value"/>
…

</chart:SfChart>
...  

ColumnSeries series = new ColumnSeries()
            {
                ItemsSource = model.CategoryData,
                XBindingPath = "XValue",
                YBindingPath = "YValue",
            };

            Chart.Legend = new ChartLegend();
            Chart.Legend.Series = series;
            Chart.Series.Add(series);
...

ItemTemplate

You can customize the appearance of legend items with your template by using ItemTemplate property of ChartLegend.

NOTE

The BindingContext of the template is the corresponding underlying legend item that provided in the ChartLegendItem class.

<chart:PieSeries ItemsSource="{Binding Data}" XBindingPath="Name" YBindingPath="Value">
    ....                 
</chart:PieSeries>

 <chart:SfChart.Legend>
    <chart:ChartLegend>
        <chart:ChartLegend.ItemTemplate>
		
            <DataTemplate>
                <StackLayout Orientation="Horizontal" WidthRequest="143">

                    <BoxView Color="{Binding IconColor}" HorizontalOptions="Center" VerticalOptions="Center" HeightRequest="13" WidthRequest="13" />

                    <Label FontSize="13" VerticalTextAlignment="Center" Text="{Binding DataPoint.Name}"/>

                    <Label HorizontalTextAlignment="End" VerticalTextAlignment="Center" HorizontalOptions="EndAndExpand" FontSize="13" Text="{Binding DataPoint.Value}"/>
					
                </StackLayout>
            </DataTemplate>

        </chart:ChartLegend.ItemTemplate>
    </chart:ChartLegend>
</chart:SfChart.Legend>
ChartLegend legend = new ChartLegend();
chart.Legend = legend;
legend.ItemTemplate = new DataTemplate ( () =>
{
    StackLayout stack = new StackLayout()
	{
		  Orientation = StackOrientation.Horizontal, WidthRequest = 143 
	};
   
    BoxView boxView = new BoxView() 
	{
		 HorizontalOptions = LayoutOptions.Center, VerticalOptions = LayoutOptions.Center, WidthRequest = 13, HeightRequest = 13 
	};
	boxView.SetBinding(BoxView.BackgroundColorProperty, "IconColor");

    Label name = new Label() 
	{
		 VerticalTextAlignment = TextAlignment.Center, FontSize = 13 
	};
	name.SetBinding(Label.TextProperty, "DataPoint.Name");

    Label value = new Label() 
	{
		 HorizontalTextAlignment = TextAlignment.End, VerticalTextAlignment = TextAlignment.Center, FontSize = 13 
	};
	value.HorizontalOptions = LayoutOptions.EndAndExpand;
	value.SetBinding(Label.TextProperty, "DataPoint.Value");

    stack.Children.Add(boxView);
    stack.Children.Add(name);
    stack.Children.Add(value);
    return stack;
});

Legend ItemTemplate support in Xamarin.Forms Chart

Event

LegendItemClicked

The LegendItemClicked event is triggered when the chart legend item is clicked. This argument contains the following information.

  • LegendItem – Used to customize the label and appearance of individual legend item.

LegendItemCreated

The LegendItemCreated event is triggered when the chart legend item is created. This argument contains the following information.

  • LegendItem – Used to customize the label and appearance of individual legend item.

You can customize the legend item using following properties of ChartLegendItem:

  • Label – Get or sets the legend item label.
  • LabelStyle – Customizes the appearance of legend labels. The properties listed in customizing label can be customized using the LabelStyle property.
  • IconColor – Gets or sets the legend icon color.
  • Index – Gets the legend item index.
  • IsEnabled – Gets the visibility of the series if the series is the type of CartesianSeries and get the visibility of the data point if the series is type of AccumulationSeries.
  • DataPoint – Gets the legend item data point for accumulation series only.
  • Series – Gets respective chart series.

NOTE

You can refer to our Xamarin Charts feature tour page for its groundbreaking feature representations. You can also explore our Xamarin.Forms Charts example to knows various chart types and how to easily configured with built-in support for creating stunning visual effects.

See also

How to apply custom fonts in Xamarin.Forms Chart

How to customize the individual legend item based on a condition in Xamarin.Forms Chart

How to collapse the series through legend

How to float the legend on chart

How to change the legend icons

How to change the legend position