2017-03-21 01:36:54 +01:00
# Legend Configuration
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
2020-01-03 20:07:38 +01:00
The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.legend` .
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 )
2019-01-29 13:34:16 +01:00
| `fullWidth` | `boolean` | `true` | Marks that this box should take the full width of the canvas (pushing down 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.
| `onHover` | `function` | | A callback that is called when a 'mousemove' event is registered on top of a label item.
2019-02-25 08:59:48 +01:00
| `onLeave` | `function` | | A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item.
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-01-31 01:27:53 +01: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
## 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'`
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
The legend label configuration is nested below the legend configuration using the `labels` key.
| Name | Type | Default | Description
2019-01-29 13:34:16 +01:00
| ---- | ---- | ------- | -----------
| `boxWidth` | `number` | `40` | Width of coloured box.
| `fontSize` | `number` | `12` | Font size of text.
| `fontStyle` | `string` | `'normal'` | Font style of text.
2018-11-02 08:46:06 +01:00
| `fontColor` | `Color` | `'#666'` | Color of text.
2019-01-29 13:34:16 +01:00
| `fontFamily` | `string` | `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` | Font family of legend text.
| `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.
2019-02-10 19:04:29 +01:00
| `usePointStyle` | `boolean` | `false` | Label style will match corresponding point style (size is based on the mimimum value between boxWidth and fontSize).
2017-03-21 01:36:54 +01:00
2020-01-11 00:28:51 +01:00
## Legend Title Configuration
The legend title configuration is nested below the legend configuration using the `title` key.
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `display` | `boolean` | `false` | Is the legend title displayed.
| `fontSize` | `number` | `12` | Font size of text.
| `fontStyle` | `string` | `'normal'` | Font style of text.
| `fontColor` | `Color` | `'#666'` | Color of text.
| `fontFamily` | `string` | `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` | Font family of legend text.
| `lineHeight` | `number` | | Line height of the text. If unset, is computed from the font size.
| `padding` | < code > number| object</ code > | `0` | Padding around the title. If specified as a number, it applies evenly to all sides.
| `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
// Fill style of the legend box
fillStyle: Color,
// 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)
2019-05-09 15:33:19 +02:00
pointStyle: string | Image,
// 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
var chart = new Chart(ctx, {
type: 'bar',
data: data,
options: {
legend: {
display: true,
labels: {
fontColor: 'rgb(255, 99, 132)'
}
}
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
function(e, legendItem) {
var index = legendItem.datasetIndex;
var ci = this.chart;
var meta = ci.getDatasetMeta(index);
// See controller.isDatasetVisible comment
2019-01-29 13:34:16 +01:00
meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null;
2017-03-21 01:36:54 +01:00
// We hid a dataset ... rerender the chart
ci.update();
}
```
Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.
```javascript
2020-01-03 20:07:38 +01:00
var defaultLegendClickHandler = Chart.defaults.legend.onClick;
2017-03-21 01:36:54 +01:00
var newLegendClickHandler = function (e, legendItem) {
var index = legendItem.datasetIndex;
if (index > 1) {
// Do the original logic
defaultLegendClickHandler(e, legendItem);
} else {
let ci = this.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();
}
};
var chart = new Chart(ctx, {
type: 'line',
data: data,
options: {
legend: {
2019-01-29 13:34:16 +01:00
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.