Legend in .NET MAUI Chart (SfCartesianChart)

10 Jan 202513 minutes to read

The Legend provides a list of series or data points, helping to identify the corresponding data series in the chart. Here’s a detailed guide on how to define and customize the legend in the chart.

Defining the legend

To define the legend in the chart, initialize the ChartLegend class and assign it to the Legend property.

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

// Assign a new instance of ChartLegend to the chart to display a legend
chart.Legend = new ChartLegend();
. . .
this.Content = chart;

Legend visibility

The visibility of the chart legend can be controlled using the IsVisible property. By default, the IsVisible property is set to true.

<chart:SfCartesianChart>
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend IsVisible="True"/>
    </chart:SfCartesianChart.Legend>
    . . .
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();

chart.Legend = new ChartLegend()
{ 
    IsVisible = true  // Set the legend's visibility
};
. . .
this.Content = chart;

Legend item visibility

The visibility of individual legend items for specific series can be controlled using the IsVisibleOnLegend property of the series. The default value for IsVisibleOnLegend is true.

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

    <chart:LineSeries ItemsSource="{Binding Data}"
                      XBindingPath="XValue"
                      YBindingPath="YValue"
                      IsVisibleOnLegend="True"/>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
chart.Legend = new ChartLegend();
LineSeries series = new LineSeries()
{
    ItemsSource = viewModel.Data,
    XBindingPath = "XValue",
    YBindingPath = "YValue",
    IsVisibleOnLegend = true, // Indicate that this series should be visible in the chart's legend
};

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

Customizing labels

The Label property of CartesianSeries 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 – Gets or sets the color of the label.
  • FontFamily - Gets or sets the font family for the legend label.
  • FontAttributes - Gets or sets the font style for the legend label.
  • FontSize - Gets or sets the font size for the legend label.
  • Margin - Gets or sets the margin size of labels.
<chart:SfCartesianChart>
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend>
            <chart:ChartLegend.LabelStyle>
                <chart:ChartLegendLabelStyle TextColor="Blue" Margin="5" FontSize="18" FontAttributes="Bold" 
                                    FontFamily="PlaywriteAR-Regular"/>
            </chart:ChartLegend.LabelStyle>
        </chart:ChartLegend>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
chart.Legend = new ChartLegend();
// Define and initialize a new `ChartLegendLabelStyle` to customize the legend label appearance.
ChartLegendLabelStyle labelStyle = new ChartLegendLabelStyle()
{
    TextColor = Color.Blue,
    Margin = new Thickness(5),
    FontSize = 18,
    FontAttributes = FontAttributes.Bold,
    FontFamily = "PlaywriteAR-Regular"
};

legend.LabelStyle = labelStyle; // Apply the label style configuration to the chart's legend.
this.Content = chart;

Legend labels customization support in Maui Chart

Legend icon

To specify the legend icon based on the associated series type, use the LegendIcon property and change its type using the ChartLegendIconType enum values. The default value of the LegendIcon property is Circle.

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

    <chart:ColumnSeries ItemsSource="{Binding Data}"
                        XBindingPath="XValue"
                        YBindingPath="YValue"
                        LegendIcon="Diamond"/>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
chart.Legend = new ChartLegend();
ViewModel viewModel = new ViewModel();

ColumnSeries columnSeries = new ColumnSeries()
{
    ItemsSource = viewModel.Data,
    XBindingPath = "XValue",
    YBindingPath = "YValue",
    LegendIcon = ChartLegendIconType.Diamond, // Set the shape of the legend icon for the series
};

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

Placement

The legend can be positioned to the left, right, top, or bottom of the chart area using the Placement property in the ChartLegend class. The default placement is Top.

<chart:SfCartesianChart>
. . .
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend Placement="Bottom"/>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
chart.Legend = new ChartLegend()
{ 
    Placement = LegendPlacement.Bottom // Set the legend placement
};

this.Content = chart;

Toggle the series visibility

The visibility of series can be controlled by tapping the legend item using the ToggleSeriesVisibility property. The default value of ToggleSeriesVisibility is false.

<chart:SfCartesianChart>
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend ToggleSeriesVisibility="True"/>
    </chart:SfCartesianChart.Legend>
    . . .
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
chart.Legend = new ChartLegend()
{ 
    ToggleSeriesVisibility = true // Enable the functionality to show/hide series by tapping on legends
};
. . .
this.Content = chart;

Legend maximum size request

To set the maximum size request for the legend view, override the GetMaximumSizeCoefficient protected method in ChartLegend class. The value should be between 0 and 1, representing the maximum size request, not the desired size for the legend items layout.

<chart:SfCartesianChart>
    <chart:SfCartesianChart.Legend>
        <chart:LegendExt/>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
// Define a custom legend class that extends ChartLegend
public class LegendExt : ChartLegend
{
    // Override the GetMaximumSizeCoefficient method to customize the legend size
    protected override double GetMaximumSizeCoefficient()
    {
        return 0.7;
    }
}

SfCartesianChart chart = new SfCartesianChart();
chart.Legend = new LegendExt(); // Set the chart's legend to use the custom LegendExt class

Items layout

The ItemsLayout property is used to customize the arrangement and position of each legend item. The default value is null. This property accepts any layout type.

<chart:SfCartesianChart x:Name="chart">
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend Placement="Bottom">
            <chart:ChartLegend.ItemsLayout>
                <FlexLayout HorizontalOptions="Start"
                            Margin="10"
                            WidthRequest="{Binding Width,
                            Source={x:Reference chart}}"/>
            </chart:ChartLegend.ItemsLayout>
        </chart:ChartLegend>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
ChartLegend legend = new ChartLegend();
legend.Placement = LegendPlacement.Bottom;

FlexLayout layout = new FlexLayout();
layout.Wrap = FlexWrap.Wrap;
layout.HorizontalOptions = LayoutOptions.Start;
layout.Margin = 10;
layout.SetBinding(WidthRequestProperty, nameof(SfCartesianChart.WidthProperty));
legend.ItemsLayout = layout;

chart.Legend = legend;
this.Content = chart;

Item template

The ChartLegend supports customizing the appearance of legend items using the ItemTemplate property. The default value of ItemsTemplate is null.

NOTE

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

<chart:SfCartesianChart x:Name="chart">
    <chart:SfCartesianChart.Resources>
        <DataTemplate x:Key="legendTemplate">
            <StackLayout Orientation="Horizontal">
                <Rectangle HeightRequest="12" 
                           WidthRequest="12" Margin="3"
                           Background="{Binding IconBrush}"/>
                <Label Text="{Binding Text}" Margin="3"/>
            </StackLayout>
        </DataTemplate>
    </chart:SfCartesianChart.Resources>  
    
    <chart:SfCartesianChart.Legend>
        <chart:ChartLegend ItemTemplate="{StaticResource legendTemplate}">
        </chart:ChartLegend>
    </chart:SfCartesianChart.Legend>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
ChartLegend legend = new ChartLegend();
// Assign a custom item template to the legend using a `DataTemplate` resource from the chart's resources.
legend.ItemTemplate = chart.Resources["legendTemplate"] as DataTemplate;
...
chart.Legend = legend;
this.Content = chart;

Legend layout for cartesian chart

Event

LegendItemCreated

The LegendItemCreated event is triggered when the chart legend item is created. The argument contains the LegendItem object. The following properties are present in LegendItem.

  • Text – used to get or set the text of the label.
  • TextColor – used to get or set the color of the label.
  • FontFamily - used to get or set the font family for the legend label.
  • FontAttributes - used to get or set the font style for the legend label.
  • FontSize - used to get or set the font size for the legend label.
  • TextMargin - used to get or set the margin size of labels.
  • IconBrush - used to change the color of the legend icon.
  • IconType - used to get or set the icon type for the legend icon.
  • IconHeight - used to get or set the icon height of the legend icon.
  • IconWidth - used to get or set the icon width of the legend icon.
  • IsToggled - used to get or set the toggle visibility of the legend.
  • DisableBrush - used to get or set the color of the legend when toggled.
  • Index - used to get index position of the legend.
  • Item - used to get the corresponding series for the legend item.

Limitations

  • Do not add items explicitly.
  • When using BindableLayouts, do not bind ItemsSource explicitly.
  • For better UX, arrange items vertically for left and right dock positions, and vice versa for top and bottom dock positions.
  • If the layout’s measured size is larger than the MaximumHeightRequest, scrolling will be enabled.
  • If MaximumHeightRequest is set to 1 and the chart’s available size is smaller than the layout’s measured size, the series may not have enough space to draw properly.