# # Legend

The chart legend displays data about the datasets that are appearing on the chart.

## # Configuration options

Namespace: `options.plugins.legend`, the global options for the chart legend is defined in `Chart.defaults.plugins.legend`.

WARNING

The doughnut, pie, and polar area charts override the legend defaults. To change the overrides for those chart types, the options are defined in `Chart.overrides[type].plugins.legend`.

Name | Type | Default | Description
--- | --- | --- | ---
`display` | `boolean` | `true` | Is the legend shown?
`position` | `string` | `'top'` | Position of the legend. more...
`align` | `string` | `'center'` | Alignment of the legend. more...
`maxHeight` | `number` |  | Maximum height of the legend, in pixels
`maxWidth` | `number` |  | Maximum width of the legend, in pixels
`fullSize` | `boolean` | `true` | Marks that this box should take the full width/height of the canvas (moving other boxes). This is unlikely to need to be changed in day-to-day use.
`onClick` | `function` |  | A callback that is called when a click event is registered on a label item. Arguments: `[event, legendItem, legend]`.
`onHover` | `function` |  | A callback that is called when a 'mousemove' event is registered on top of a label item. Arguments: `[event, legendItem, legend]`.
`onLeave` | `function` |  | A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item. Arguments: `[event, legendItem, legend]`.
`reverse` | `boolean` | `false` | Legend will show datasets in reverse order.
`labels` | `object` |  | See the Legend Label Configuration section below.
`rtl` | `boolean` |  | `true` for rendering the legends from right to left.
`textDirection` | `string` | canvas' default | This will force the text direction `'rtl'` or `'ltr'` on the canvas for rendering the legend, regardless of the css specified on the canvas
`title` | `object` |  | See the Legend Title Configuration section below.

## # Position

Position of the legend. Options are:

- `'top'`
- `'left'`
- `'bottom'`
- `'right'`
- `'chartArea'`

When using the `'chartArea'` option the legend position is at the moment not configurable, it will always be on the left side of the chart in the middle.

## # Align

Alignment of the legend. Options are:

- `'start'`
- `'center'`
- `'end'`

Defaults to `'center'` for unrecognized values.

## # Legend Label Configuration

Namespace: `options.plugins.legend.labels`

Name | Type | Default | Description
--- | --- | --- | ---
`boxWidth` | `number` | `40` | Width of coloured box.
`boxHeight` | `number` | `font.size` | Height of the coloured box.
`color` | `Color` | `Chart.defaults.color` | Color of label and the strikethrough.
`font` | `Font` | `Chart.defaults.font` | See Fonts
`padding` | `number` | `10` | Padding between rows of colored boxes.
`generateLabels` | `function` |  | Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See Legend Item for details.
`filter` | `function` | `null` | Filters legend items out of the legend. Receives 2 parameters, a Legend Item and the chart data.
`sort` | `function` | `null` | Sorts legend items. Type is : `sort(a: LegendItem, b: LegendItem, data: ChartData): number;`. Receives 3 parameters, two Legend Items and the chart data. The return value of the function is a number that indicates the order of the two legend item parameters. The ordering matches the return value (opens new window) of `Array.prototype.sort()`
`pointStyle` | `pointStyle` | `'circle'` | If specified, this style of point is used for the legend. Only used if `usePointStyle` is true.
`textAlign` | `string` | `'center'` | Horizontal alignment of the label text. Options are: `'left'`, `'right'` or `'center'`.
`usePointStyle` | `boolean` | `false` | Label style will match corresponding point style (size is based on pointStyleWidth or the minimum value between boxWidth and font.size).
`pointStyleWidth` | `number` | `null` | If `usePointStyle` is true, the width of the point style used for the legend (only for `circle`, `rect` and `line` point stlye).

## # Legend Title Configuration

Namespace: `options.plugins.legend.title`

Name | Type | Default | Description
--- | --- | --- | ---
`color` | `Color` | `Chart.defaults.color` | Color of text.
`display` | `boolean` | `false` | Is the legend title displayed.
`font` | `Font` | `Chart.defaults.font` | See Fonts
`padding` | `Padding` | `0` | Padding around the title.
`text` | `string` |  | The string title.

## # Legend Item Interface

Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface.

    {
        // Label that will be displayed
        text: string,
        // Border radius of the legend item.
        // Introduced in 3.1.0
        borderRadius?: number | BorderRadius,
        // Index of the associated dataset
        datasetIndex: number,
        // Fill style of the legend box
        fillStyle: Color,
        // Text color
        fontColor: Color,
        // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
        hidden: boolean,
        // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
        lineCap: string,
        // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
        lineDash: number[],
        // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
        lineDashOffset: number,
        // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
        lineJoin: string,
        // Width of box border
        lineWidth: number,
        // Stroke style of the legend box
        strokeStyle: Color,
        // Point style of the legend box (only used if usePointStyle is true)
        pointStyle: string | Image | HTMLCanvasElement,
        // Rotation of the point in degrees (only used if usePointStyle is true)
        rotation: number
    }

## # Example

The following example will create a chart with the legend enabled and turn all of the text red in color.

    const chart = new Chart(ctx, {
        type: 'bar',
        data: data,
        options: {
            plugins: {
                legend: {
                    display: true,
                    labels: {
                        color: 'rgb(255, 99, 132)'
                    }
                }
            }
        }
    });

## # Custom On Click Actions

It can be common to want to trigger different behaviour when clicking an item in the legend. This can be easily achieved using a callback in the config object.

The default legend click handler is:

    function(e, legendItem, legend) {
        const index = legendItem.datasetIndex;
        const ci = legend.chart;
        if (ci.isDatasetVisible(index)) {
            ci.hide(index);
            legendItem.hidden = true;
        } else {
            ci.show(index);
            legendItem.hidden = false;
        }
    }

Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.

    const defaultLegendClickHandler = Chart.defaults.plugins.legend.onClick;
    const pieDoughnutLegendClickHandler = Chart.controllers.doughnut.overrides.plugins.legend.onClick;
    const newLegendClickHandler = function (e, legendItem, legend) {
        const index = legendItem.datasetIndex;
        const type = legend.chart.config.type;
        if (index > 1) {
            // Do the original logic
            if (type === 'pie' || type === 'doughnut') {
                pieDoughnutLegendClickHandler(e, legendItem, legend)
            } else {
                defaultLegendClickHandler(e, legendItem, legend);
            }
        } else {
            let ci = legend.chart;
            [
                ci.getDatasetMeta(0),
                ci.getDatasetMeta(1)
            ].forEach(function(meta) {
                meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null;
            });
            ci.update();
        }
    };
    const chart = new Chart(ctx, {
        type: 'line',
        data: data,
        options: {
            plugins: {
                legend: {
                    onClick: newLegendClickHandler
                }
            }
        }
    });

Now when you click the legend in this chart, the visibility of the first two datasets will be linked together.