| commit | author | age | ||
| 83c3f6 | 1 | # Legend Configuration |
| SP | 2 | |
| 3 | The chart legend displays data about the datasets that are appearing on the chart. | |
| 4 | ||
| 5 | ## Configuration options | |
| 6 | The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`. | |
| 7 | ||
| 8 | | Name | Type | Default | Description | |
| 9 | | -----| ---- | --------| ----------- | |
| 10 | | `display` | `Boolean` | `true` | is the legend shown | |
| 11 | | `position` | `String` | `'top'` | Position of the legend. [more...](#position) | |
| 12 | | `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. | |
| 13 | | `onClick` | `Function` | | A callback that is called when a click event is registered on a label item | |
| 14 | | `onHover` | `Function` | | A callback that is called when a 'mousemove' event is registered on top of a label item | |
| 15 | | `reverse` | `Boolean` | `false` | Legend will show datasets in reverse order. | |
| 16 | | `labels` | `Object` | | See the [Legend Label Configuration](#legend-label-configuration) section below. | |
| 17 | ||
| 18 | ## Position | |
| 19 | Position of the legend. Options are: | |
| 20 | * `'top'` | |
| 21 | * `'left'` | |
| 22 | * `'bottom'` | |
| 23 | * `'right'` | |
| 24 | ||
| 25 | ## Legend Label Configuration | |
| 26 | ||
| 27 | The legend label configuration is nested below the legend configuration using the `labels` key. | |
| 28 | ||
| 29 | | Name | Type | Default | Description | |
| 30 | | -----| ---- | --------| ----------- | |
| 31 | | `boxWidth` | `Number` | `40` | width of coloured box | |
| 32 | | `fontSize` | `Number` | `12` | font size of text | |
| 33 | | `fontStyle` | `String` | `'normal'` | font style of text | |
| 34 | | `fontColor` | `Color` | `'#666'` | Color of text | |
| 35 | | `fontFamily` | `String` | `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` | Font family of legend text. | |
| 36 | | `padding` | `Number` | `10` | Padding between rows of colored boxes. | |
| 37 | | `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. | |
| 38 | | `filter` | `Function` | `null` | Filters legend items out of the legend. Receives 2 parameters, a [Legend Item](#legend-item-interface) and the chart data. | |
| 39 | | `usePointStyle` | `Boolean` | `false` | Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). | |
| 40 | ||
| 41 | ## Legend Item Interface | |
| 42 | ||
| 43 | Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface. | |
| 44 | ||
| 45 | ```javascript | |
| 46 | { | |
| 47 | // Label that will be displayed | |
| 48 | text: String, | |
| 49 | ||
| 50 | // Fill style of the legend box | |
| 51 | fillStyle: Color, | |
| 52 | ||
| 53 | // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect | |
| 54 | hidden: Boolean, | |
| 55 | ||
| 56 | // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap | |
| 57 | lineCap: String, | |
| 58 | ||
| 59 | // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash | |
| 60 | lineDash: Array[Number], | |
| 61 | ||
| 62 | // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset | |
| 63 | lineDashOffset: Number, | |
| 64 | ||
| 65 | // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin | |
| 66 | lineJoin: String, | |
| 67 | ||
| 68 | // Width of box border | |
| 69 | lineWidth: Number, | |
| 70 | ||
| 71 | // Stroke style of the legend box | |
| 72 | strokeStyle: Color | |
| 73 | ||
| 74 | // Point style of the legend box (only used if usePointStyle is true) | |
| 75 | pointStyle: String | |
| 76 | } | |
| 77 | ``` | |
| 78 | ||
| 79 | ## Example | |
| 80 | ||
| 81 | The following example will create a chart with the legend enabled and turn all of the text red in color. | |
| 82 | ||
| 83 | ```javascript | |
| 84 | var chart = new Chart(ctx, { | |
| 85 | type: 'bar', | |
| 86 | data: data, | |
| 87 | options: { | |
| 88 | legend: { | |
| 89 | display: true, | |
| 90 | labels: { | |
| 91 | fontColor: 'rgb(255, 99, 132)' | |
| 92 | } | |
| 93 | } | |
| 94 | } | |
| 95 | }); | |
| 96 | ``` | |
| 97 | ||
| 98 | ## Custom On Click Actions | |
| 99 | ||
| 100 | 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. | |
| 101 | ||
| 102 | The default legend click handler is: | |
| 103 | ```javascript | |
| 104 | function(e, legendItem) { | |
| 105 | var index = legendItem.datasetIndex; | |
| 106 | var ci = this.chart; | |
| 107 | var meta = ci.getDatasetMeta(index); | |
| 108 | ||
| 109 | // See controller.isDatasetVisible comment | |
| 110 | meta.hidden = meta.hidden === null? !ci.data.datasets[index].hidden : null; | |
| 111 | ||
| 112 | // We hid a dataset ... rerender the chart | |
| 113 | ci.update(); | |
| 114 | } | |
| 115 | ``` | |
| 116 | ||
| 117 | Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly. | |
| 118 | ||
| 119 | ```javascript | |
| 120 | var defaultLegendClickHandler = Chart.defaults.global.legend.onClick; | |
| 121 | var newLegendClickHandler = function (e, legendItem) { | |
| 122 | var index = legendItem.datasetIndex; | |
| 123 | ||
| 124 | if (index > 1) { | |
| 125 | // Do the original logic | |
| 126 | defaultLegendClickHandler(e, legendItem); | |
| 127 | } else { | |
| 128 | let ci = this.chart; | |
| 129 | [ci.getDatasetMeta(0), | |
| 130 | ci.getDatasetMeta(1)].forEach(function(meta) { | |
| 131 | meta.hidden = meta.hidden === null? !ci.data.datasets[index].hidden : null; | |
| 132 | }); | |
| 133 | ci.update(); | |
| 134 | } | |
| 135 | }; | |
| 136 | ||
| 137 | var chart = new Chart(ctx, { | |
| 138 | type: 'line', | |
| 139 | data: data, | |
| 140 | options: { | |
| 141 | legend: { | |
| 142 | ||
| 143 | } | |
| 144 | } | |
| 145 | }); | |
| 146 | ``` | |
| 147 | ||
| 148 | Now when you click the legend in this chart, the visibility of the first two datasets will be linked together. | |
| 149 | ||
| 150 | ## HTML Legends | |
| 151 | ||
| 152 | 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. | |
| 153 | ||
| 154 | To configure how this legend is generated, you can change the `legendCallback` config property. | |
| 155 | ||
| 156 | ```javascript | |
| 157 | var chart = new Chart(ctx, { | |
| 158 | type: 'line', | |
| 159 | data: data, | |
| 160 | options: { | |
| 161 | legendCallback: function(chart) { | |
| 162 | // Return the HTML string here. | |
| 163 | } | |
| 164 | } | |
| 165 | }); | |
| 166 | ``` | |
| 167 | ||
| 168 | Note that legendCallback is not called automatically and you must call `generateLegend()` yourself in code when creating a legend using this method. | |
| 169 | ||
| 170 | ||
