legend

Specifies the options of a chart's legend.

Type:

Object

The Chart widget can include a legend - an explanatory component that helps you identify a series. Each series is represented by an item on a Legend. An item marker identifies the series color. An item label displays the series title. To set the required position for a legend and its items, to customize the font settings for item labels, and to specify the size of item markers, use the properties of the legend configuration object. To learn more on the legend and its options, refer to the Legend topic.

backgroundColor

Colors the legend's background.

Type:

String

Default Value: undefined

This option supports the following colors:

border

Configures the legend's border.

Type:

Object

columnCount

Arranges legend items into several columns.

Type:

Number

Default Value: 0

Use this option when the legend is oriented vertically. Otherwise, use rowCount.

See Also

columnItemSpacing

Specifies an empty space between item columns in pixels.

Type:

Number

Default Value: 20

customizeHint

Specifies the text for a hint that appears when a user hovers the mouse pointer over a legend item.

Type:

Function

Function parameters:
seriesInfo:

Object

Information on the series.

Object structure:
Name Type Description
seriesColor

String

The series' color.

seriesIndex

Number

The index of the series in the series array. To get the Series object by this index, call the getSeriesByPos(seriesIndex) method.

seriesName any

The series' name. To get the Series object by this name, call the getSeriesByName(seriesName) method.

Return Value:

String

The text for the hint to display.

NOTE
As an alternative to the function’s parameter you can use the this keyword.

customizeItems

Allows you to change the order, text, and visibility of legend items.

Type:

Function

Function parameters:

Legend items before customizations.

Return Value:

Array<BaseChartLegendItem>

Legend items after customizations.

The following code shows how to use the customizeItems function to sort legend items alphabetically:

jQuery
JavaScript
$(function() {
    $("#chartContainer").dxChart({
        // ...
        legend: {
            customizeItems: function(items) {
                return items.sort(function(a, b) {
                    var itemA = a.text.toLowerCase();
                    var itemB = b.text.toLowerCase();
                    if(itemA < itemB) return -1;
                    if(itemA > itemB) return 1;
                    return 0;
                });
            }
        }
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-chart ... >
    <dxo-legend ...
        [customizeItems]="sortLegendItems">
    </dxo-legend>
</dx-chart>
// ...
export class AppComponent {
    sortLegendItems(items) {
        return items.sort((a, b) => {
            let itemA = a.text.toLowerCase();
            let itemB = b.text.toLowerCase();
            if(itemA < itemB) return -1;
            if(itemA > itemB) return 1;
            return 0;
        });
    }
}
import { DxChartModule } from 'devextreme-angular';
// ...
@NgModule({
    imports: [
        // ...
        DxChartModule
    ],
    // ...
})
export class AppModule { }
Vue
App.vue
<template> 
    <dx-chart ... >
        <dx-legend
            :customize-items="sortLegendItems"
        />
    </dx-chart>
</template>

<script>
import { DxChart, DxLegend } from 'devextreme-vue/chart';

export default {
    components: {
        DxChart,
        DxLegend
    },
    methods: {
        sortLegendItems(items) {
            return items.sort((a, b) => {
                let itemA = a.text.toLowerCase();
                let itemB = b.text.toLowerCase();
                if(itemA < itemB) return -1;
                if(itemA > itemB) return 1;
                return 0;
            });
        }
    }
}
</script>
React
App.js
import React from 'react';
import { Chart, Legend } from 'devextreme-react/chart';

class App extends React.Component {
    render() {
        return (
            <Chart ... >
                <Legend ...
                    customizeItems={this.sortLegendItems}
                />
            </Chart>
        );
    }

    sortLegendItems(items) {
        return items.sort((a, b) => {
            let itemA = a.text.toLowerCase();
            let itemB = b.text.toLowerCase();
            if(itemA < itemB) return -1;
            if(itemA > itemB) return 1;
            return 0;
        });
    }
}

export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().Chart()
    @* ... *@
    .Legend(l => l
        .CustomizeItems("sortLegendItems")
    )
)

<script type="text/javascript">
    function sortLegendItems (items) {
        return items.sort(function(a, b) {
            var itemA = a.text.toLowerCase();
            var itemB = b.text.toLowerCase();
            if(itemA < itemB) return -1;
            if(itemA > itemB) return 1;
            return 0;
        });
    }
</script>

customizeText

Specifies a callback function that returns the text to be displayed by a legend item.

Type:

Function

Function parameters:
seriesInfo:

Object

Information on the series.

Object structure:
Name Type Description
seriesColor

String

The series' color.

seriesIndex

Number

The series' index.

seriesName any

The series' name.

Return Value:

String

The text for the legend item to display.

Cannot be used in themes.
NOTE
As an alternative to the function’s parameter you can use the this keyword.

font

Specifies the legend items' font options.

Type:

Object

horizontalAlignment

Along with verticalAlignment, specifies the legend's position.

Type:

String

Default Value: 'right'
Accepted Values: 'center' | 'left' | 'right'

Use the HorizontalAlignment enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Left, Center, and Right.

See Also

hoverMode

Specifies what series elements to highlight when a corresponding item in the legend is hovered over.

Type:

String

Default Value: 'includePoints'
Accepted Values: 'excludePoints' | 'includePoints' | 'none'

In the Chart widget, legend items represent series. When a legend item is hovered over, the corresponding series is highlighted. To prevent this behavior, set the hoverMode property to 'none'.

You can set a custom 'hover' style for a series and/or its points. To do this, use the series' hoverStyle configuration object and/or the point.hoverStyle configuration object.

Use the ChartLegendHoverMode enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: IncludePoints, ExcludePoints, and None.

View Demo

itemsAlignment

Aligns items in the last column or row (depending on the legend's orientation). Applies when legend items are not divided into columns or rows equally.

Type:

String

Default Value: undefined
Accepted Values: 'center' | 'left' | 'right'

Use the HorizontalAlignment enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Left, Center, and Right.

itemTextPosition

Specifies the text's position relative to the marker in a legend item.

Type:

String

Default Value: undefined
Accepted Values: 'bottom' | 'left' | 'right' | 'top'

margin

Generates an empty space, measured in pixels, around the legend.

Type:

Number

|

Object

Default Value: 10

When set to a number, this option applies to all the legend's sides. The object allows you to control each side individually.

DevExtreme Legend Margins

markerSize

Specifies the marker's size in a legend item in pixels.

Type:

Number

Default Value: 20

orientation

Arranges legend items vertically (in a column) or horizontally (in a row). The default value is "horizontal" if the legend.horizontalAlignment is "center". Otherwise, it is "vertical".

Type:

String

Default Value: undefined
Accepted Values: 'horizontal' | 'vertical'

Use the Orientation enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Horizontal and Vertical.

See Also

paddingLeftRight

Generates an empty space, measured in pixels, between the legend's left/right border and its items.

Type:

Number

Default Value: 10

DevExtreme Legend Left-Right Padding

paddingTopBottom

Generates an empty space, measured in pixels, between the legend's top/bottom border and its items.

Type:

Number

Default Value: 10

DevExtreme Legend Top-Bottom Padding

position

Specifies whether the legend is located outside or inside the chart's plot.

Type:

String

Default Value: 'outside'
Accepted Values: 'inside' | 'outside'

In addition to this option, use the legend's horizontalAlignment, verticalAlignment and orientation options to specify the legend layout.

Use the RelativePosition enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Inside and Outside.

rowCount

Arranges legend items in several rows.

Type:

Number

Default Value: 0

Use this option when the legend is oriented horizontally. Otherwise, use columnCount.

See Also

rowItemSpacing

Specifies an empty space between item rows in pixels.

Type:

Number

Default Value: 8

title

Configures the legend title.

Type:

Object

|

String

DevExtreme PieChart: Legend Title

To specify only the title's text, assign it directly to this option. Otherwise, set this option to an object with the text and other fields specified.

The title can be accompanied by a subtitle. Assign it to the title.subtitle option.

verticalAlignment

Along with horizontalAlignment, specifies the legend's position.

Type:

String

Default Value: 'top'
Accepted Values: 'bottom' | 'top'

Use the VerticalEdge enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Top and Bottom.

See Also

visible

Specifies the legend's visibility.

Type:

Boolean

Default Value: true