Legend Configuration

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

Configuration options

The legend configuration is passed into the options.legend namespace. The global options for the chart legend is defined in Chart.defaults.global.legend.

NameTypeDefaultDescription
displayBooleantrueis the legend shown
positionString'top'Position of the legend. more…
fullWidthBooleantrueMarks 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.
onClickFunctionA callback that is called when a click event is registered on a label item
onHoverFunctionA callback that is called when a 'mousemove' event is registered on top of a label item
reverseBooleanfalseLegend will show datasets in reverse order.
labelsObjectSee the Legend Label Configuration section below.

Position

Position of the legend. Options are:

  • 'top'
  • 'left'
  • 'bottom'
  • 'right'

Legend Label Configuration

The legend label configuration is nested below the legend configuration using the labels key.

NameTypeDefaultDescription
boxWidthNumber40width of coloured box
fontSizeNumber12font size of text
fontStyleString'normal'font style of text
fontColorColor'#666'Color of text
fontFamilyString"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"Font family of legend text.
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.
usePointStyleBooleanfalseLabel style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case).

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. // Fill style of the legend box
  5. fillStyle: Color,
  6. // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
  7. hidden: Boolean,
  8. // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
  9. lineCap: String,
  10. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
  11. lineDash: Array[Number],
  12. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
  13. lineDashOffset: Number,
  14. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
  15. lineJoin: String,
  16. // Width of box border
  17. lineWidth: Number,
  18. // Stroke style of the legend box
  19. strokeStyle: Color
  20. // Point style of the legend box (only used if usePointStyle is true)
  21. pointStyle: String
  22. }

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. legend: {
  6. display: true,
  7. labels: {
  8. fontColor: 'rgb(255, 99, 132)'
  9. }
  10. }
  11. }
  12. });

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) {
  2. var index = legendItem.datasetIndex;
  3. var ci = this.chart;
  4. var meta = ci.getDatasetMeta(index);
  5. // See controller.isDatasetVisible comment
  6. meta.hidden = meta.hidden === null? !ci.data.datasets[index].hidden : null;
  7. // We hid a dataset ... rerender the chart
  8. ci.update();
  9. }

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

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

HTML Legends

Sometimes you need a very complex legend. In these cases, it makes sense to generate an HTML legend. Charts provide a generateLegend() method on their prototype that returns an HTML string for the legend.

To configure how this legend is generated, you can change the legendCallback config property.

  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. legendCallback: function(chart) {
  6. // Return the HTML string here.
  7. }
  8. }
  9. });

Note that legendCallback is not called automatically and you must call generateLegend() yourself in code when creating a legend using this method.