# Legends | WPF Controls | DevExpress Documentation A legend is a chart element that allows you to distinguish between [series](/WPF/6339/controls-and-libraries/charts-suite/chart-control/series/series) on a chart. In addition to series, a legend can display [series points](/WPF/6340/controls-and-libraries/charts-suite/chart-control/series/series-points), [indicators](/WPF/115226/controls-and-libraries/charts-suite/chart-control/series/indicators), [strips](/WPF/7848/controls-and-libraries/charts-suite/chart-control/axes/strips) and [constant lines](/WPF/7846/controls-and-libraries/charts-suite/chart-control/axes/constant-lines). To identify chart elements, a legend displays a marker, a check box, or both - with the specified text. Marker appearance (shape and color) differs based on the element’s type. ![WPF_Legend_LegendItems](/WPF/images/wpf_legend_legenditems122120.png) Note The Chart Control can hide its elements if there is insufficient space to display them. Elements are hidden in the following order: 1. **Legends** 2. [Axis Titles](/WPF/7096/controls-and-libraries/charts-suite/chart-control/axes/axis-titles) 3. [Series Titles](/WPF/7941/controls-and-libraries/charts-suite/chart-control/series/series-titles) 4. [Pane Titles](/WPF/400428/controls-and-libraries/charts-suite/chart-control/panes/pane-titles) 5. [Axes](/WPF/6334/controls-and-libraries/charts-suite/chart-control/axes/axes) 6. [Chart Title](/WPF/7844/controls-and-libraries/charts-suite/chart-control/chart-titles) 7. [Breadcrumbs](/WPF/400717/controls-and-libraries/charts-suite/chart-control/provide-data/drill-down#customize-text-the-chart-displays-in-the-breadcrumb-panel) To make the Chart Control always display its elements, disable the [ChartControl.AutoLayout](/WPF/DevExpress.Xpf.Charts.ChartControlBase.AutoLayout) property. ## How to Add a Legend If the legend’s position options are undefined, it is positioned in the the top-right corner of the chart. Use the following XAML to add a legend to a chart: - XAML 
<dxc:ChartControl.Legends> 
        <dxc:Legend/> 
</dxc:ChartControl.Legends>
The example above uses the following classes and properties: | Member | Description | | --- | --- | | [ChartControlBase.Legends](/WPF/DevExpress.Xpf.Charts.ChartControlBase.Legends) | Returns a collection that stores chart legends. | | [Legend](/WPF/DevExpress.Xpf.Charts.Legend) | A legend. | A legend displays chart elements (series, indicator, constant line, and strip) whose **Visible** and **ShowInLegend** properties are enabled. To specify text that identifies a series in a legend, use the [Series.DisplayName](/WPF/DevExpress.Xpf.Charts.Series.DisplayName) property. Use the [Indicator.LegendText](/WPF/DevExpress.Xpf.Charts.Indicator.LegendText), [ConstantLine.LegendText](/WPF/DevExpress.Xpf.Charts.ConstantLine.LegendText), and [Strip.LegendText](/WPF/DevExpress.Xpf.Charts.Strip.LegendText) properties to define the legend text for an indicator, a constant line, and a strip, respectively. When the **DisplayName** or **LegendText** property is set to [Empty](https://learn.microsoft.com/dotnet/api/system.string.empty#system-string-empty), the legend does not show a chart element. In addition to series, indicators, constant lines, and strips, a legend can contain series point values. The legend for a [Simple 2D Diagram](/WPF/115309/controls-and-libraries/charts-suite/chart-control/diagram/simple-2d-diagram) (or [Simple 3D Diagram](/WPF/115311/controls-and-libraries/charts-suite/chart-control/diagram/simple-3d-diagram)) displays point values. Enable the [XYSeries.ColorEach](/WPF/DevExpress.Xpf.Charts.XYSeries.ColorEach) property to show points in legends of Cartesian ([2D XY Diagram](/WPF/115312/controls-and-libraries/charts-suite/chart-control/diagram/2d-xy-diagram), [3D XY Diagram](/WPF/115313/controls-and-libraries/charts-suite/chart-control/diagram/3d-xy-diagram)) and Circular ([2D Polar Diagram](/WPF/115307/controls-and-libraries/charts-suite/chart-control/diagram/2d-polar-diagram), [2D Radar Diagram](/WPF/115308/controls-and-libraries/charts-suite/chart-control/diagram/2d-radar-diagram)) diagrams. You can add multiple legends to a chart as shown below: ![chart-multiple-legends](/WPF/images/chart-multiple-legends132552.png) The following example shows how to add several legends: - XAML 
<dxc:ChartControl>
    <dxc:ChartControl.Legends>
        <dxc:Legend x:Name="topLegend" DockTarget="{Binding ElementName=topPane}"/>
        <dxc:Legend x:Name="bottomLegend" DockTarget="{Binding ElementName=bottomPane}"/>
    </dxc:ChartControl.Legends>
    <dxc:XYDiagram2D>                
        <dxc:XYDiagram2D.DefaultPane>
            <dxc:Pane x:Name="topPane"/>
        </dxc:XYDiagram2D.DefaultPane>
        <dxc:XYDiagram2D.Panes>
            <dxc:Pane x:Name="bottomPane"/>
        </dxc:XYDiagram2D.Panes>
        <dxc:AreaSeries2D DisplayName="Pressure (mbar)" 
                          Pane="{Binding ElementName=bottomPane}"
                          Legend="{Binding ElementName=bottomLegend}"/>
    </dxc:XYDiagram2D>
</dxc:ChartControl>
The markup uses the following API members: | Member | Description | | --- | --- | | [Legend.DockTarget](/WPF/DevExpress.Xpf.Charts.Legend.DockTarget) | Specifies the [pane](/WPF/10631/controls-and-libraries/charts-suite/chart-control/panes/panes) (or its View Model) that contains a legend. | | [Series.Legend](/WPF/DevExpress.Xpf.Charts.Series.Legend) | Gets or sets the legend (or its View Model) that displays information about the series. | ## How to Specify Legend Layout You can modify the legend’s vertical and horizontal positions, and place the legend inside or outside of a diagram. You can also display legend items in a column or row, and show them in reversed order. ![legend-layout](/WPF/images/legend-layout132555.png) Use the notation below to place a legend at the bottom of the chart - outside the diagram - and align it horizontally to the center as shown in the previous image. - XAML 
<dxc:ChartControl.Legends>
    <dxc:Legend HorizontalPosition="Center" 
                VerticalPosition="BottomOutside"
                Orientation="Horizontal"
                ReverseItems="True"
                IndentFromDiagram="0,16,0,0"/>
</dxc:ChartControl.Legends>
The following API members manage the legend and its item positions: | Member | Description | | --- | --- | | [LegendBase.HorizontalPosition](/WPF/DevExpress.Xpf.Charts.LegendBase.HorizontalPosition) | Specifies the legend’s horizontal position within a chart. | | [LegendBase.VerticalPosition](/WPF/DevExpress.Xpf.Charts.LegendBase.VerticalPosition) | Specifies the legend’s vertical position within a chart. | | [LegendBase.Orientation](/WPF/DevExpress.Xpf.Charts.LegendBase.Orientation) | Defines vertical or horizontal legend item orientation. | | [Legend.ReverseItems](/WPF/DevExpress.Xpf.Charts.Legend.ReverseItems) | Gets or sets whether the legend item order is reversed. | | [LegendBase.IndentFromDiagram](/WPF/DevExpress.Xpf.Charts.LegendBase.IndentFromDiagram) | Specifies the space between the legend and the diagram. | Also, you can use the [LegendBase.ItemsPanel](/WPF/DevExpress.Xpf.Charts.LegendBase.ItemsPanel) property to customize the legend item layout. ## 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. ![chart-legend-title](/WPF/images/chart-legend-title132561.png) Use the code below to configure a legend’s title: - XAML 
<dxc:ChartControl.Legends>
    <dxc:Legend>
        <dxc:Legend.Title>
            <dxc:LegendTitle Content="Year" 
                             HorizontalAlignment="Center"/>
        </dxc:Legend.Title>
    </dxc:Legend>
</dxc:ChartControl.Legends>
The following classes and properties allow you to add and modify a legend’s title: | Member | Description | | --- | --- | | [LegendBase.Title](/WPF/DevExpress.Xpf.Charts.LegendBase.Title) | Specifies a legend title. | | [LegendTitle](/WPF/DevExpress.Xpf.Charts.LegendTitle) | A legend title. | | [TitleBase.Content](/WPF/DevExpress.Xpf.Charts.TitleBase.Content) | Gets or sets the title’s content. | | [TitleBase.HorizontalAlignment](/WPF/DevExpress.Xpf.Charts.TitleBase.HorizontalAlignment) | Specifies how the title is horizontally aligned. | ## How to Enable Check Boxes in a Legend You can use check boxes in a legend to manage the visibility of series, indicators, strips, and constant lines as shown below: ![legend-check-box-marker](/WPF/images/legend-check-box-marker132562.png) Note Check boxes for series points are not available. Configure the [Series.FilterCriteria](/WPF/DevExpress.Xpf.Charts.Series.FilterCriteria) property to hide specific points. Use the following code to display legend items with check boxes: - XAML 
<dxc:ChartControl.Legends>
    <dxc:Legend MarkerMode="CheckBoxAndMarker"/>
</dxc:ChartControl.Legends>
The markup above uses the following API members: | Member | Description | | --- | --- | | [Legend.MarkerMode](/WPF/DevExpress.Xpf.Charts.Legend.MarkerMode) | Specifies a mode that defines how to display legend markers. | | [LegendMarkerMode](/WPF/DevExpress.Xpf.Charts.LegendMarkerMode) | Lists values that specify which marker type a legend uses. | Use the chart element’s **CheckableInLegend** ([Series.CheckableInLegend](/WPF/DevExpress.Xpf.Charts.Series.CheckableInLegend), [Indicator.CheckableInLegend](/WPF/DevExpress.Xpf.Charts.Indicator.CheckableInLegend), [ConstantLine.CheckableInLegend](/WPF/DevExpress.Xpf.Charts.ConstantLine.CheckableInLegend), [Strip.CheckableInLegend](/WPF/DevExpress.Xpf.Charts.Strip.CheckableInLegend)) property to specify whether a legend shows a check box for the element. Use the **CheckedInLegend** ([Series.CheckedInLegend](/WPF/DevExpress.Xpf.Charts.Series.CheckedInLegend), [Indicator.CheckedInLegend](/WPF/DevExpress.Xpf.Charts.Indicator.CheckedInLegend), [ConstantLine.CheckedInLegend](/WPF/DevExpress.Xpf.Charts.ConstantLine.CheckedInLegend), [Strip.CheckedInLegend](/WPF/DevExpress.Xpf.Charts.Strip.CheckedInLegend)) property to select or clear an element’s legend check box. ## How to Format Legend Item Text When the **ColorEach** mode is enabled, you can format legend item text using format specifiers, placeholders and plain text. ![legend-text-pattern](/WPF/images/legend-text-pattern132574.png) 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. - XAML 
<dxc:PieSeries2D LegendTextPattern="{}{A}: ${V}M">
      <!-- Other series settings. -->
</dxc:PieSeries2D>
The example demonstrates how to use the following property. | Member | Description | | --- | --- | | [Series.LegendTextPattern](/WPF/DevExpress.Xpf.Charts.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)](/WindowsForms/2967/controls-and-libraries/chart-control/series-views/2d-series-views/pie-and-donut-series-views) 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](/WindowsForms/5212/controls-and-libraries/chart-control/series-views/2d-series-views/point-and-line-series-views/bubble-chart) 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](/WindowsForms/2971/controls-and-libraries/chart-control/series-views/2d-series-views/financial-series-views) series specific placeholders | | {OV} | Displays the *open value*. | | {HV} | Displays the *high value*. | | {LV} | Displays the *low value*. | | {CV} | Displays the *close value*. | Note Before you use the *{S}* placeholder, ensure that the [Series.Name](/CoreLibraries/DevExpress.XtraCharts.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, if the data source contains the **Discount** field, the text pattern might appear as follows: *{S}: {V:F2} (Discount: {Discount:P0})*. ## Customize Legend Item Appearance Specify the [LegendBase.ItemTemplate](/WPF/DevExpress.Xpf.Charts.LegendBase.ItemTemplate) property to assign a data template that defines legend item appearance: - XAML 
<dxc:ChartControl.Legends>
    <dxc:Legend HorizontalPosition="Left" 
                VerticalPosition="Top" 
                Orientation="Vertical">
        <dxc:Legend.ItemTemplate>
            <DataTemplate>
                <dxc:LegendItemContainer>
                    <Grid Width="12" Height="12">
                        <Rectangle Stretch="Uniform" 
                                   Fill="Transparent"/>
                        <dxc:ChartContentPresenter Content="{Binding}" 
                                                   ContentTemplate="{Binding Path=MarkerTemplate}"/>
                    </Grid>
                    <TextBlock Text="{Binding Path=Text}" 
                               VerticalAlignment="Center" 
                               MaxWidth="250" 
                               Margin="4"
                               Foreground="{Binding Path=MarkerBrush}"/>
                </dxc:LegendItemContainer>
            </DataTemplate>
        </dxc:Legend.ItemTemplate>
    </dxc:Legend>
</dxc:ChartControl.Legends>
## How to Add a Custom Legend Item You can add custom legend items in addition to items that are automatically generated. ![legend-custom-item](/WPF/images/legend-custom-item132583.png) The following code shows how to create a custom legend item: - XAML 
<dxc:ChartControl.Legends>
    <dxc:Legend ItemVisibilityMode="AutoGeneratedAndCustom">
        <dxc:Legend.CustomItems>
            <dxc:CustomLegendItem Text="Total: $4390M"
                                  MarkerBrush="#FFC3C3C3">
                <dxc:CustomLegendItem.MarkerTemplate>
                    <DataTemplate>
                        <Image Source="/Images/sum.png"/>
                    </DataTemplate>
                </dxc:CustomLegendItem.MarkerTemplate>
            </dxc:CustomLegendItem>
        </dxc:Legend.CustomItems>
    </dxc:Legend>
</dxc:ChartControl.Legends>
The example uses the following classes and properties: | Member | Description | | --- | --- | | [LegendBase.CustomItems](/WPF/DevExpress.Xpf.Charts.LegendBase.CustomItems) | The legend’s custom items collection. | | [CustomLegendItem](/WPF/DevExpress.Xpf.Charts.CustomLegendItem) | A custom legend item. | | [CustomLegendItem.Text](/WPF/DevExpress.Xpf.Charts.CustomLegendItem.Text) | Text that the custom legend item displays. | | [CustomLegendItem.MarkerBrush](/WPF/DevExpress.Xpf.Charts.CustomLegendItem.MarkerBrush) | Specifies a brush that is used to draw a legend item’s marker. | | [CustomLegendItem.MarkerTemplate](/WPF/DevExpress.Xpf.Charts.CustomLegendItem.MarkerTemplate) | Gets or sets the template that defines a custom legend item’s marker appearance. | | [LegendBase.ItemVisibilityMode](/WPF/DevExpress.Xpf.Charts.LegendBase.ItemVisibilityMode) | Defines the mode used to display custom and automatically generated items. | | [LegendItemVisibilityMode](/WPF/DevExpress.Xpf.Charts.LegendItemVisibilityMode) | Lists modes that specify custom and default legend item visibility. | To generate a chart element collection from a chart’s View Model, bind the [LegendBase.CustomItemsSource](/WPF/DevExpress.Xpf.Charts.LegendBase.CustomItemsSource) property to the View Model’s property and specify the [LegendBase.CustomItemTemplate](/WPF/DevExpress.Xpf.Charts.LegendBase.CustomItemTemplate) or [LegendBase.CustomItemTemplateSelector](/WPF/DevExpress.Xpf.Charts.LegendBase.CustomItemTemplateSelector) property to bind the element’s properties to the element view model’s properties. See Also [How to: Add an Additional Legend](/WPF/116011/controls-and-libraries/charts-suite/chart-control/examples/chart-elements/how-to-add-an-additional-legend) [How to: Add a Legend Title to a Legend](/WPF/116012/controls-and-libraries/charts-suite/chart-control/examples/chart-elements/how-to-add-a-legend-title-to-a-legend) [How to: Add a Custom Legend Items to a Legend](/WPF/116013/controls-and-libraries/charts-suite/chart-control/examples/chart-elements/how-to-add-a-custom-legend-items-to-a-legend) [How to: Create a Scrollable Legend](/WPF/10783/controls-and-libraries/charts-suite/chart-control/examples/chart-elements/how-to-create-a-scrollable-legend) [How to: Create a Movable Legend at Runtime](/WPF/11115/controls-and-libraries/charts-suite/chart-control/examples/end-user-interaction/how-to-create-a-movable-legend-at-runtime) [How to: Display Values Instead of Percents in the Legend](/WPF/8384/controls-and-libraries/charts-suite/chart-control/examples/chart-elements/how-to-display-values-instead-of-percents-in-the-legend)