[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
 [Expand]What's Installed
 [Expand].NET Core 3 Support
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Collapse]Controls and Libraries
  [Expand]Data Grid
  [Expand]Ribbon, Bars and Menu
  [Collapse]Charts Suite
   [Collapse]Chart Control
    [Expand]Getting Started
    [Expand]Providing Data
    [Collapse]Chart Elements
      Chart Titles
    [Expand]Appearance Customization
    [Expand]End-User Features
    [Expand]Design-Time Features
    [Expand]Additional Resources
   [Expand]Chart3D Control
  [Expand]Pivot Grid
  [Expand]Rich Text Editor
  [Expand]Tree List
  [Expand]Gauge Controls
  [Expand]Map Control
  [Expand]Layout Management
  [Expand]Windows Modern UI
  [Expand]Data Editors
  [Expand]Navigation Controls
  [Expand]Spell Checker
  [Expand]Property Grid
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Gantt Control
  [Expand]Diagram Control
  [Expand]Windows and Utility Controls
   Dialogs, Notifications and Panels
  [Expand]Scheduler (legacy)
 [Expand]Scaffolding Wizard
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)


A legend is a chart element that allows you to distinguish between Series on a chart. In addition to series, a legend can display Series Points, Indicators, Strips and Constant Lines. To identify chart elements, a legend displays a marker (check box or both) with the specified text. Marker appearance (shape and color) differs depending on an element's type.

This topic consists of the following sections:

Expanded How to Add a Legend

The legend occupies the default position at the top-right corner of a chart, if legend position's options are undefined. Use the following XAML to add a legend to a chart:

The example above uses the following classes and properties:

Member Description
ChartControlBase.Legends The chart legends' collection.
Legend A legend.

A legend displays chart elements (series, indicator, constant line, and strip) whose Visible and ShowInLegend properties are enabled. To specify a text that identifies a series in a legend, use the Series.DisplayName property. Use the Indicator.LegendText, ConstantLine.LegendText, Strip.LegendText property to define a legend text for an indicator, constant line, or a strip. When the DisplayName or LegendText property is set to System.String.Empty, a legend does not show a chart element.

In addition to series, indicators, constant lines, and strips, a legend can contain series points' values. A Simple 2D Diagram (Simple 3D Diagram)'s legend displays points' values by default. Enable the XYSeries.ColorEach property to show points in legends of the Cartesian (2D XY Diagram, 3D XY Diagram) and Circular (2D Polar Diagram, 2D Radar Diagram) diagrams.

You can add multiple legends to a chart as shown below:

The following example shows how to add several legends:

The markup uses the following API members:

Member Description
Legend.DockTarget Specifies the pane (or its View Model) that contains a legend.
Series.Legend Gets or sets the legend (or its View Model) that displays information about the series.

Expanded How to Specify Legend Layout

You can modify vertical and horizontal legend's position, and place a legend within or outside a diagram. Also, you can display legend items in a column or row, and show them in the reversed order.

Use the notation below to place a legend to the bottom of the chart outside the diagram and align it horizontally to center as shown in the previous image.

The following API members manage legend and its items' positions:

Member Description
Legend.HorizontalPosition Specifies the legend's horizontal position within a chart.
Legend.VerticalPosition Specifies the legend's vertical position within a chart.
Legend.Orientation Defines vertical or horizontal legend items' orientation.
Legend.ReverseItems Gets or sets whether legend items have an original order or reversed.
Legend.IndentFromDiagram Specifies a space between a legend and a diagram.

Also, you can use the Legend.ItemsPanel property to customize legend items' layout.

Expanded How to Add a Title to a Legend

A legend can only contain a single title. You can configure the title's content and its horizontal alignment within a legend.

Use the code below to configure a legend's title:

The following classes and properties allow you to add and modify a legend's title:

Member Description
Legend.Title Specifies a legend title.
LegendTitle A legend title.
TitleBase.Content Gets or sets the title's content.
TitleBase.HorizontalAlignment Specifies how the title is horizontally aligned.

Expanded How to Enable Check Boxes in a Legend

You can manage chart elements' visibility using check boxes in a legend as shown below:

Use the following code to display legend items with check boxes:

The markup above uses the following API members:

Member Description
Legend.MarkerMode Specifies a mode defying how to display legend markers.
LegendMarkerMode Lists values that specify which marker type a legend uses.

Use the chart element's CheckableInLegend (Series.CheckableInLegend, Indicator.CheckableInLegend, ConstantLine.CheckableInLegend, Strip.CheckableInLegend) property to specify whether a legend shows a check box for the element.

Use the CheckedInLegend (Series.CheckedInLegend, Indicator.CheckedInLegend, ConstantLine.CheckedInLegend, Strip.CheckedInLegend, CustomLegendItem.CheckedInLegend) property to select or clear an element's legend check box.

Expanded How to Format Legend Item Text

When the ColorEach mode is enabled, you can format legend items' text using format specifiers, placeholders and plain text.

The following markup shows how to format text that identifies series points in a legend. In the format string, the A and V placeholders define point argument and value.

The example demonstrates how to use the following property.

Member Description
Series.LegendTextPattern Specifies a pattern formatting legend text for series points.

A full list of available placeholders is detailed below.

Pattern Description
{S} Displays the name of the series.
{A} Displays a series point argument.
{V} Displays series point values.
Pie (Donut) series specific placeholders
{VP} Displays series point values as percentages.
{TV} Displays a total group value.
Stacked series specific placeholders
{VP} Displays series point values as percentages.
{G} Displays the name of a stacked group.
{TV} Displays a total group value.
Bubble series specific placeholders
{W} Displays the weight.
Range series specific placeholders
{V1} Displays the first value.
{V2} Displays the second value.
{VD} Displays the duration between the first and second data point values formatted using a common time format (e.g. HH:MM:SS for date time values and #.## for numeric values).
{VDTD} Displays the duration between the first and second date-time data point values in days.
{VDTH} Displays the duration between the first and second date-time data point values in hours.
{VDTM} Displays the duration between the first and second date-time data point values in minutes.
{VDTS} Displays the duration between the first and second date-time data point values in seconds.
{VDTMS} Displays the duration between the first and second date-time data point values in milliseconds.
Financial series specific placeholders
{OV} Displays the open value.
{HV} Displays the high value.
{LV} Displays the low value.
{CV} Displays the close value.

Make sure before using the {S} placeholder that the Series.Name property is specified.

You can also use standard and custom format specifiers, together with the placeholders and data field values (e.g., {V:F1}).

When the chart control or a series is bound to data, the text pattern may contain data field values in addition to default placeholders. For example, the data source contains the Discount field and the text pattern may looks like: {S}: {V:F2} (Discount: {Discount:P0}).

Define the Legend.ItemTemplate property to specify legend item appearance.

Expanded How to Add a Custom Legend Item

You can add custom legend items in addition to items that automatically generated by default.

The following code shows how to create a custom legend item:

The example uses the following classes and properties:

Member Description
Legend.CustomItems The legend's custom items collection.
CustomLegendItem A custom legend item.
CustomLegendItem.Text Text the custom legend item displays.
CustomLegendItem.MarkerBrush Specifies a brush that is used to draw a legend item's marker.
CustomLegendItem.MarkerTemplate Gets or sets the template that defines a custom legend item's marker appearance.
Legend.ItemVisibilityMode Defines the mode used to display custom and automatically generated items.
LegendItemVisibilityMode Lists modes that specify custom and default legend items' visibility.

To generate a chart element collection from a chart's View Model, bind the Legend.CustomItemsSource property to the View Model's property and specify the Legend.CustomItemTemplate or Legend.CustomItemTemplateSelector to bind the element's properties to the element view model's properties.

Expanded See Also

Is this topic helpful?​​​​​​​