| commit | author | age | ||
| 83c3f6 | 1 | # Line |
| SP | 2 | A line chart is a way of plotting data points on a line. Often, it is used to show trend data, or the comparison of two data sets. |
| 3 | ||
| 4 | {% chartjs %} | |
| 5 | { | |
| 6 | "type": "line", | |
| 7 | "data": { | |
| 8 | "labels": [ | |
| 9 | "January", | |
| 10 | "February", | |
| 11 | "March", | |
| 12 | "April", | |
| 13 | "May", | |
| 14 | "June", | |
| 15 | "July" | |
| 16 | ], | |
| 17 | "datasets": [{ | |
| 18 | "label": "My First Dataset", | |
| 19 | "data": [65, 59, 80, 81, 56, 55, 40], | |
| 20 | "fill": false, | |
| 21 | "borderColor": "rgb(75, 192, 192)", | |
| 22 | "lineTension": 0.1 | |
| 23 | }] | |
| 24 | }, | |
| 25 | "options": { | |
| 26 | ||
| 27 | } | |
| 28 | } | |
| 29 | {% endchartjs %} | |
| 30 | ||
| 31 | ## Example Usage | |
| 32 | ```javascript | |
| 33 | var myLineChart = new Chart(ctx, { | |
| 34 | type: 'line', | |
| 35 | data: data, | |
| 36 | options: options | |
| 37 | }); | |
| 38 | ``` | |
| 39 | ||
| 40 | ## Dataset Properties | |
| 41 | ||
| 42 | The line chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a line is generally set this way. | |
| 43 | ||
| 44 | All point* properties can be specified as an array. If these are set to an array value, the first value applies to the first point, the second value to the second point, and so on. | |
| 45 | ||
| 46 | | Name | Type | Description | |
| 47 | | ---- | ---- | ----------- | |
| 48 | | `label` | `String` | The label for the dataset which appears in the legend and tooltips. | |
| 49 | | `xAxisID` | `String` | The ID of the x axis to plot this dataset on. If not specified, this defaults to the ID of the first found x axis | |
| 50 | | `yAxisID` | `String` | The ID of the y axis to plot this dataset on. If not specified, this defaults to the ID of the first found y axis. | |
| 51 | | `backgroundColor` | `Color` | The fill color under the line. See [Colors](../general/colors.md#colors) | |
| 52 | | `borderColor` | `Color` | The color of the line. See [Colors](../general/colors.md#colors) | |
| 53 | | `borderWidth` | `Number` | The width of the line in pixels. | |
| 54 | | `borderDash` | `Number[]` | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) | |
| 55 | | `borderDashOffset` | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) | |
| 56 | | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) | |
| 57 | | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) | |
| 58 | | `cubicInterpolationMode` | `String` | Algorithm used to interpolate a smooth curve from the discrete data points. [more...](#cubicinterpolationmode) | |
| 59 | | `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md) | |
| 60 | | `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. | |
| 61 | | `pointBackgroundColor` | `Color/Color[]` | The fill color for points. | |
| 62 | | `pointBorderColor` | `Color/Color[]` | The border color for points. | |
| 63 | | `pointBorderWidth` | `Number/Number[]` | The width of the point border in pixels. | |
| 64 | | `pointRadius` | `Number/Number[]` | The radius of the point shape. If set to 0, the point is not rendered. | |
| 65 | | `pointStyle` | `String/String[]/Image/Image[]` | Style of the point. [more...](../configuration/elements#point-styles) | |
| 66 | | `pointRotation` | `Number/Number[]` | The rotation of the point in degrees. | |
| 67 | | `pointHitRadius` | `Number/Number[]` | The pixel size of the non-displayed point that reacts to mouse events. | |
| 68 | | `pointHoverBackgroundColor` | `Color/Color[]` | Point background color when hovered. | |
| 69 | | `pointHoverBorderColor` | `Color/Color[]` | Point border color when hovered. | |
| 70 | | `pointHoverBorderWidth` | `Number/Number[]` | Border width of point when hovered. | |
| 71 | | `pointHoverRadius` | `Number/Number[]` | The radius of the point when hovered. | |
| 72 | | `showLine` | `Boolean` | If false, the line is not drawn for this dataset. | |
| 73 | | `spanGaps` | `Boolean` | If true, lines will be drawn between points with no or null data. If false, points with `NaN` data will create a break in the line | |
| 74 | | `steppedLine` | `Boolean/String` | If the line is shown as a stepped line. [more...](#stepped-line) | |
| 75 | ||
| 76 | ### cubicInterpolationMode | |
| 77 | The following interpolation modes are supported: | |
| 78 | * 'default' | |
| 79 | * 'monotone'. | |
| 80 | ||
| 81 | The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. | |
| 82 | ||
| 83 | The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. | |
| 84 | ||
| 85 | If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used. | |
| 86 | ||
| 87 | ### Stepped Line | |
| 88 | The following values are supported for `steppedLine`: | |
| 89 | * `false`: No Step Interpolation (default) | |
| 90 | * `true`: Step-before Interpolation (eq. 'before') | |
| 91 | * `'before'`: Step-before Interpolation | |
| 92 | * `'after'`: Step-after Interpolation | |
| 93 | ||
| 94 | If the `steppedLine` value is set to anything other than false, `lineTension` will be ignored. | |
| 95 | ||
| 96 | ## Configuration Options | |
| 97 | ||
| 98 | The line chart defines the following configuration options. These options are merged with the global chart configuration options, `Chart.defaults.global`, to form the options passed to the chart. | |
| 99 | ||
| 100 | | Name | Type | Default | Description | |
| 101 | | ---- | ---- | ------- | ----------- | |
| 102 | | `showLines` | `Boolean` | `true` | If false, the lines between points are not drawn. | |
| 103 | | `spanGaps` | `Boolean` | `false` | If false, NaN data causes a break in the line. | |
| 104 | ||
| 105 | ## Default Options | |
| 106 | ||
| 107 | It is common to want to apply a configuration setting to all created line charts. The global line chart settings are stored in `Chart.defaults.line`. Changing the global options only affects charts created after the change. Existing charts are not changed. | |
| 108 | ||
| 109 | For example, to configure all line charts with `spanGaps = true` you would do: | |
| 110 | ```javascript | |
| 111 | Chart.defaults.line.spanGaps = true; | |
| 112 | ``` | |
| 113 | ||
| 114 | ## Data Structure | |
| 115 | ||
| 116 | The `data` property of a dataset for a line chart can be passed in two formats. | |
| 117 | ||
| 118 | ### Number[] | |
| 119 | ```javascript | |
| 120 | data: [20, 10] | |
| 121 | ``` | |
| 122 | ||
| 123 | When the `data` array is an array of numbers, the x axis is generally a [category](../axes/cartesian/category.md#category-cartesian-axis). The points are placed onto the axis using their position in the array. When a line chart is created with a category axis, the `labels` property of the data object must be specified. | |
| 124 | ||
| 125 | ### Point[] | |
| 126 | ||
| 127 | ```javascript | |
| 128 | data: [{ | |
| 129 | x: 10, | |
| 130 | y: 20 | |
| 131 | }, { | |
| 132 | x: 15, | |
| 133 | y: 10 | |
| 134 | }] | |
| 135 | ``` | |
| 136 | ||
| 137 | This alternate is used for sparse datasets, such as those in [scatter charts](./scatter.md#scatter-chart). Each data point is specified using an object containing `x` and `y` properties. | |
| 138 | ||
| 139 | # Stacked Area Chart | |
| 140 | ||
| 141 | Line charts can be configured into stacked area charts by changing the settings on the y axis to enable stacking. Stacked area charts can be used to show how one data trend is made up of a number of smaller pieces. | |
| 142 | ||
| 143 | ```javascript | |
| 144 | var stackedLine = new Chart(ctx, { | |
| 145 | type: 'line', | |
| 146 | data: data, | |
| 147 | options: { | |
| 148 | scales: { | |
| 149 | yAxes: [{ | |
| 150 | stacked: true | |
| 151 | }] | |
| 152 | } | |
| 153 | } | |
| 154 | }); | |
| 155 | ``` | |
| 156 | ||
| 157 | # High Performance Line Charts | |
| 158 | ||
| 159 | When charting a lot of data, the chart render time may start to get quite large. In that case, the following strategies can be used to improve performance. | |
| 160 | ||
| 161 | ## Data Decimation | |
| 162 | ||
| 163 | Decimating your data will achieve the best results. When there is a lot of data to display on the graph, it doesn't make sense to show tens of thousands of data points on a graph that is only a few hundred pixels wide. | |
| 164 | ||
| 165 | There are many approaches to data decimation and selection of an algorithm will depend on your data and the results you want to achieve. For instance, [min/max](http://digital.ni.com/public.nsf/allkb/F694FFEEA0ACF282862576020075F784) decimation will preserve peaks in your data but could require up to 4 points for each pixel. This type of decimation would work well for a very noisy signal where you need to see data peaks. | |
| 166 | ||
| 167 | ## Disable Bezier Curves | |
| 168 | ||
| 169 | If you are drawing lines on your chart, disabling bezier curves will improve render times since drawing a straight line is more performant than a bezier curve. | |
| 170 | ||
| 171 | To disable bezier curves for an entire chart: | |
| 172 | ||
| 173 | ```javascript | |
| 174 | new Chart(ctx, { | |
| 175 | type: 'line', | |
| 176 | data: data, | |
| 177 | options: { | |
| 178 | elements: { | |
| 179 | line: { | |
| 180 | tension: 0, // disables bezier curves | |
| 181 | } | |
| 182 | } | |
| 183 | } | |
| 184 | }); | |
| 185 | ``` | |
| 186 | ||
| 187 | ## Disable Line Drawing | |
| 188 | ||
| 189 | If you have a lot of data points, it can be more performant to disable rendering of the line for a dataset and only draw points. Doing this means that there is less to draw on the canvas which will improve render performance. | |
| 190 | ||
| 191 | To disable lines: | |
| 192 | ||
| 193 | ```javascript | |
| 194 | new Chart(ctx, { | |
| 195 | type: 'line', | |
| 196 | data: { | |
| 197 | datasets: [{ | |
| 198 | showLine: false, // disable for a single dataset | |
| 199 | }] | |
| 200 | }, | |
| 201 | options: { | |
| 202 | showLines: false, // disable for all datasets | |
| 203 | } | |
| 204 | }); | |
| 205 | ``` | |
| 206 | ||
| 207 | ## Disable Animations | |
| 208 | ||
| 209 | If your charts have long render times, it is a good idea to disable animations. Doing so will mean that the chart needs to only be rendered once during an update instead of multiple times. This will have the effect of reducing CPU usage and improving general page performance. | |
| 210 | ||
| 211 | To disable animations | |
| 212 | ||
| 213 | ```javascript | |
| 214 | new Chart(ctx, { | |
| 215 | type: 'line', | |
| 216 | data: data, | |
| 217 | options: { | |
| 218 | animation: { | |
| 219 | duration: 0, // general animation time | |
| 220 | }, | |
| 221 | hover: { | |
| 222 | animationDuration: 0, // duration of animations when hovering an item | |
| 223 | }, | |
| 224 | responsiveAnimationDuration: 0, // animation duration after a resize | |
| 225 | } | |
| 226 | }); | |
| 227 | ``` | |
