2021-03-30 16:32:39 +02:00
# Legend
2017-03-21 01:36:54 +01:00
2018-03-20 15:37:56 +01:00
The chart legend displays data about the datasets that are appearing on the chart.
2017-03-21 01:36:54 +01:00
## Configuration options
2020-01-03 15:08:15 +01:00
2021-02-19 17:44:05 +01:00
Namespace: `options.plugins.legend` , the global options for the chart legend is defined in `Chart.defaults.plugins.legend` .
2017-03-21 01:36:54 +01:00
2021-10-24 18:14:37 +02:00
:::warning
2021-10-25 18:48:51 +02:00
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` .
2021-10-24 18:14:37 +02:00
:::
2017-03-21 01:36:54 +01:00
| Name | Type | Default | Description
2019-01-29 13:34:16 +01:00
| ---- | ---- | ------- | -----------
| `display` | `boolean` | `true` | Is the legend shown?
| `position` | `string` | `'top'` | Position of the legend. [more... ](#position )
2019-03-23 10:25:17 +01:00
| `align` | `string` | `'center'` | Alignment of the legend. [more... ](#align )
2020-12-18 21:03:01 +01:00
| `maxHeight` | `number` | | Maximum height of the legend, in pixels
| `maxWidth` | `number` | | Maximum width of the legend, in pixels
2021-01-31 19:44:44 +01:00
| `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.
2020-05-24 16:28:41 +02:00
| `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]` .
2019-01-29 13:34:16 +01:00
| `reverse` | `boolean` | `false` | Legend will show datasets in reverse order.
| `labels` | `object` | | See the [Legend Label Configuration ](#legend-label-configuration ) section below.
2019-09-12 01:20:03 +02:00
| `rtl` | `boolean` | | `true` for rendering the legends from right to left.
2020-05-21 23:07:06 +02:00
| `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
2020-01-11 00:28:51 +01:00
| `title` | `object` | | See the [Legend Title Configuration ](#legend-title-configuration ) section below.
2017-03-21 01:36:54 +01:00
2022-11-08 01:49:47 +01:00
:::tip Note
If you need more visual customizations, please use an [HTML legend ](../samples/legend/html.md ).
:::
2017-03-21 01:36:54 +01:00
## Position
2020-01-03 15:08:15 +01:00
2017-03-21 01:36:54 +01:00
Position of the legend. Options are:
2020-01-03 15:08:15 +01:00
2017-03-21 01:36:54 +01:00
* `'top'`
* `'left'`
* `'bottom'`
* `'right'`
2021-03-07 21:43:31 +01:00
* `'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.
2017-03-21 01:36:54 +01:00
2019-03-23 10:25:17 +01:00
## Align
2020-01-03 15:08:15 +01:00
2019-03-23 10:25:17 +01:00
Alignment of the legend. Options are:
2020-01-03 15:08:15 +01:00
2019-03-23 10:25:17 +01:00
* `'start'`
* `'center'`
* `'end'`
Defaults to `'center'` for unrecognized values.
2017-03-21 01:36:54 +01:00
## Legend Label Configuration
2021-02-19 17:44:05 +01:00
Namespace: `options.plugins.legend.labels`
2017-03-21 01:36:54 +01:00
| Name | Type | Default | Description
2019-01-29 13:34:16 +01:00
| ---- | ---- | ------- | -----------
| `boxWidth` | `number` | `40` | Width of coloured box.
2020-12-18 21:03:01 +01:00
| `boxHeight` | `number` | `font.size` | Height of the coloured box.
2021-01-10 21:17:02 +01:00
| `color` | [`Color` ](../general/colors.md ) | `Chart.defaults.color` | Color of label and the strikethrough.
2020-12-18 21:03:01 +01:00
| `font` | `Font` | `Chart.defaults.font` | See [Fonts ](../general/fonts.md )
2019-01-29 13:34:16 +01:00
| `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 ](#legend-item-interface ) for details.
| `filter` | `function` | `null` | Filters legend items out of the legend. Receives 2 parameters, a [Legend Item ](#legend-item-interface ) and the chart data.
2022-11-08 01:49:47 +01:00
| `sort` | `function` | `null` | Sorts legend items. Type is : `sort(a: LegendItem, b: LegendItem, data: ChartData): number;` . Receives 3 parameters, two [Legend Items ](#legend-item-interface ) 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 ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description ) of `Array.prototype.sort()`
2021-07-30 14:14:07 +02:00
| [`pointStyle` ](elements.md#point-styles ) | [`pointStyle` ](elements.md#types ) | `'circle'` | If specified, this style of point is used for the legend. Only used if `usePointStyle` is true.
2021-03-18 12:37:03 +01:00
| `textAlign` | `string` | `'center'` | Horizontal alignment of the label text. Options are: `'left'` , `'right'` or `'center'` .
2022-07-18 12:49:08 +02:00
| `usePointStyle` | `boolean` | `false` | Label style will match corresponding point style (size is based on pointStyleWidth or the minimum value between boxWidth and font.size).
2022-09-01 12:37:12 +02:00
| `pointStyleWidth` | `number` | `null` | If `usePointStyle` is true, the width of the point style used for the legend.
2022-10-19 14:02:20 +02:00
| `useBorderRadius` | `boolean` | `false` | Label borderRadius will match corresponding borderRadius.
2022-08-18 13:34:18 +02:00
| `borderRadius` | `number` | `undefined` | Override the borderRadius to use.
2017-03-21 01:36:54 +01:00
2020-01-11 00:28:51 +01:00
## Legend Title Configuration
2021-02-19 17:44:05 +01:00
Namespace: `options.plugins.legend.title`
2020-01-11 00:28:51 +01:00
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
2020-12-18 21:03:01 +01:00
| `color` | [`Color` ](../general/colors.md ) | `Chart.defaults.color` | Color of text.
2020-01-11 00:28:51 +01:00
| `display` | `boolean` | `false` | Is the legend title displayed.
2020-12-18 21:03:01 +01:00
| `font` | `Font` | `Chart.defaults.font` | See [Fonts ](../general/fonts.md )
2021-03-14 16:21:30 +01:00
| `padding` | [`Padding` ](../general/padding.md ) | `0` | Padding around the title.
2020-01-11 00:28:51 +01:00
| `text` | `string` | | The string title.
2017-03-21 01:36:54 +01:00
## Legend Item Interface
Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels` . These items must implement the following interface.
```javascript
{
// Label that will be displayed
2019-01-29 13:34:16 +01:00
text: string,
2017-03-21 01:36:54 +01:00
2021-04-10 21:05:34 +02:00
// Border radius of the legend item.
// Introduced in 3.1.0
borderRadius?: number | BorderRadius,
2020-12-18 18:46:54 +01:00
// Index of the associated dataset
datasetIndex: number,
2017-03-21 01:36:54 +01:00
// Fill style of the legend box
fillStyle: Color,
2021-04-03 17:55:27 +02:00
// Text color
fontColor: Color,
2017-03-21 01:36:54 +01:00
// If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
2019-01-29 13:34:16 +01:00
hidden: boolean,
2017-03-21 01:36:54 +01:00
// For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
2019-01-29 13:34:16 +01:00
lineCap: string,
2017-03-21 01:36:54 +01:00
// For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
2019-01-29 13:34:16 +01:00
lineDash: number[],
2017-03-21 01:36:54 +01:00
// For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
2019-01-29 13:34:16 +01:00
lineDashOffset: number,
2017-03-21 01:36:54 +01:00
// For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
2019-01-29 13:34:16 +01:00
lineJoin: string,
2017-03-21 01:36:54 +01:00
// Width of box border
2019-01-29 13:34:16 +01:00
lineWidth: number,
2017-03-21 01:36:54 +01:00
// Stroke style of the legend box
2019-01-29 13:34:16 +01:00
strokeStyle: Color,
2017-03-21 01:36:54 +01:00
// Point style of the legend box (only used if usePointStyle is true)
2021-07-23 07:26:49 +02:00
pointStyle: string | Image | HTMLCanvasElement,
2019-05-09 15:33:19 +02:00
// Rotation of the point in degrees (only used if usePointStyle is true)
rotation: number
2017-03-21 01:36:54 +01:00
}
```
## Example
The following example will create a chart with the legend enabled and turn all of the text red in color.
```javascript
2021-10-13 20:51:33 +02:00
const chart = new Chart(ctx, {
2017-03-21 01:36:54 +01:00
type: 'bar',
data: data,
options: {
2020-11-25 07:50:12 +01:00
plugins: {
legend: {
display: true,
labels: {
2020-12-05 20:34:34 +01:00
color: 'rgb(255, 99, 132)'
2020-11-25 07:50:12 +01:00
}
2017-03-21 01:36:54 +01:00
}
}
2019-01-29 13:34:16 +01:00
}
2017-03-21 01:36:54 +01:00
});
```
## 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:
2020-01-03 15:08:15 +01:00
2017-03-21 01:36:54 +01:00
```javascript
2020-05-24 16:28:41 +02:00
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;
}
2017-03-21 01:36:54 +01:00
}
```
Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.
```javascript
2021-10-13 20:51:33 +02:00
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;
2017-03-21 01:36:54 +01:00
if (index > 1) {
// Do the original logic
2021-06-02 21:48:04 +02:00
if (type === 'pie' || type === 'doughnut') {
pieDoughnutLegendClickHandler(e, legendItem, legend)
} else {
defaultLegendClickHandler(e, legendItem, legend);
}
2017-03-21 01:36:54 +01:00
} else {
2020-05-24 16:28:41 +02:00
let ci = legend.chart;
2019-01-29 13:34:16 +01:00
[
ci.getDatasetMeta(0),
ci.getDatasetMeta(1)
].forEach(function(meta) {
meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null;
2017-03-21 01:36:54 +01:00
});
ci.update();
}
};
2021-10-13 20:51:33 +02:00
const chart = new Chart(ctx, {
2017-03-21 01:36:54 +01:00
type: 'line',
data: data,
options: {
2020-11-25 07:50:12 +01:00
plugins: {
legend: {
onClick: newLegendClickHandler
}
2017-03-21 01:36:54 +01:00
}
}
});
```
Now when you click the legend in this chart, the visibility of the first two datasets will be linked together.