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.

NameTypeDefaultDescription
displaybooleantrueIs the legend shown?
positionstring‘top’Position of the legend. more…
alignstring‘center’Alignment of the legend. more…
maxHeightnumberMaximum height of the legend, in pixels
maxWidthnumberMaximum width of the legend, in pixels
fullSizebooleantrueMarks 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.
onClickfunctionA callback that is called when a click event is registered on a label item. Arguments: [event, legendItem, legend].
onHoverfunctionA callback that is called when a ‘mousemove’ event is registered on top of a label item. Arguments: [event, legendItem, legend].
onLeavefunctionA callback that is called when a ‘mousemove’ event is registered outside of a previously hovered label item. Arguments: [event, legendItem, legend].
reversebooleanfalseLegend will show datasets in reverse order.
labelsobjectSee the Legend Label Configuration section below.
rtlbooleantrue for rendering the legends from right to left.
textDirectionstringcanvas’ defaultThis will force the text direction ‘rtl’ or ‘ltr’ on the canvas for rendering the legend, regardless of the css specified on the canvas
titleobjectSee 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

NameTypeDefaultDescription
boxWidthnumber40Width of coloured box.
boxHeightnumberfont.sizeHeight of the coloured box.
colorColorChart.defaults.colorColor of label and the strikethrough.
fontFontChart.defaults.fontSee Fonts
paddingnumber10Padding between rows of colored boxes.
generateLabelsfunctionGenerates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See Legend Item for details.
filterfunctionnullFilters legend items out of the legend. Receives 2 parameters, a Legend Item and the chart data.
sortfunctionnullSorts legend items. Receives 3 parameters, two Legend Items and the chart data.
pointStyleIf specified, this style of point is used for the legend. Only used if usePointStyle is true.
textAlignstring‘center’Horizontal alignment of the label text. Options are: ‘left’, ‘right’ or ‘center’.
usePointStylebooleanfalseLabel style will match corresponding point style (size is based on the minimum value between boxWidth and font.size).

Legend Title Configuration

Namespace: options.plugins.legend.title

NameTypeDefaultDescription
colorColorChart.defaults.colorColor of text.
displaybooleanfalseIs the legend title displayed.
fontFontChart.defaults.fontSee Fonts
paddingPadding0Padding around the title.
textstringThe 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.

  1. {
  2. // Label that will be displayed
  3. text: string,
  4. // Border radius of the legend item.
  5. // Introduced in 3.1.0
  6. borderRadius?: number | BorderRadius,
  7. // Index of the associated dataset
  8. datasetIndex: number,
  9. // Fill style of the legend box
  10. fillStyle: Color,
  11. // Text color
  12. fontColor: Color,
  13. // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
  14. hidden: boolean,
  15. // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
  16. lineCap: string,
  17. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
  18. lineDash: number[],
  19. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
  20. lineDashOffset: number,
  21. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
  22. lineJoin: string,
  23. // Width of box border
  24. lineWidth: number,
  25. // Stroke style of the legend box
  26. strokeStyle: Color,
  27. // Point style of the legend box (only used if usePointStyle is true)
  28. pointStyle: string | Image,
  29. // Rotation of the point in degrees (only used if usePointStyle is true)
  30. rotation: number
  31. }

Example

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

  1. var chart = new Chart(ctx, {
  2. type: 'bar',
  3. data: data,
  4. options: {
  5. plugins: {
  6. legend: {
  7. display: true,
  8. labels: {
  9. color: 'rgb(255, 99, 132)'
  10. }
  11. }
  12. }
  13. }
  14. });

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:

  1. function(e, legendItem, legend) {
  2. const index = legendItem.datasetIndex;
  3. const ci = legend.chart;
  4. if (ci.isDatasetVisible(index)) {
  5. ci.hide(index);
  6. legendItem.hidden = true;
  7. } else {
  8. ci.show(index);
  9. legendItem.hidden = false;
  10. }
  11. }

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

  1. var defaultLegendClickHandler = Chart.defaults.plugins.legend.onClick;
  2. var newLegendClickHandler = function (e, legendItem, legend) {
  3. var index = legendItem.datasetIndex;
  4. if (index > 1) {
  5. // Do the original logic
  6. defaultLegendClickHandler(e, legendItem, legend);
  7. } else {
  8. let ci = legend.chart;
  9. [
  10. ci.getDatasetMeta(0),
  11. ci.getDatasetMeta(1)
  12. ].forEach(function(meta) {
  13. meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null;
  14. });
  15. ci.update();
  16. }
  17. };
  18. var chart = new Chart(ctx, {
  19. type: 'line',
  20. data: data,
  21. options: {
  22. plugins: {
  23. legend: {
  24. onClick: newLegendClickHandler
  25. }
  26. }
  27. }
  28. });

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