diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5ec896e40ca..041be7062af 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -27,6 +27,7 @@ * [Polar Area](charts/polar.md) * [Bubble](charts/bubble.md) * [Scatter](charts/scatter.md) + * [Area](charts/area.md) * [Mixed](charts/mixed.md) * [Axes](axes/README.md) * [Cartesian](axes/cartesian/README.md) diff --git a/docs/charts/README.md b/docs/charts/README.md index 44622096641..26677b04d76 100644 --- a/docs/charts/README.md +++ b/docs/charts/README.md @@ -8,4 +8,6 @@ Chart.js comes with built-in chart types: * [doughnut and pie](./doughnut.md) * [bubble](./bubble.md) -To create a new chart type, see the [developer notes](../developers/charts.md#new-charts) \ No newline at end of file +[Area charts](area.md) can be built from a line or radar chart using the dataset `fill` option. + +To create a new chart type, see the [developer notes](../developers/charts.md#new-charts) diff --git a/docs/charts/area.md b/docs/charts/area.md new file mode 100644 index 00000000000..d51f84754a5 --- /dev/null +++ b/docs/charts/area.md @@ -0,0 +1,72 @@ +# Area Charts + +Both [line](line.md) and [radar](radar.md) charts support a `fill` option on the dataset object which can be used to create area between two datasets or a dataset and a boundary, i.e. the scale `origin`, `start` or `end` (see [filling modes](#filling-modes)). + +> **Note:** this feature is implemented by the [`filler` plugin](/chartjs/Chart.js/blob/master/src/plugins/plugin.filler.js). + +## Filling modes + +| Mode | Type | Values | +| :--- | :--- | :--- | +| Absolute dataset index 1 | `Number` | `1`, `2`, `3`, ... | +| Relative dataset index 1 | `String` | `'-1'`, `'-2'`, `'+1'`, ... | +| Boundary 2 | `String` | `'start'`, `'end'`, `'origin'` | +| Disabled 3 | `Boolean` | `false` | + +> 1 dataset filling modes have been introduced in version 2.6.0
+> 2 prior version 2.6.0, boundary values was `'zero'`, `'top'`, `'bottom'` (deprecated)
+> 3 for backward compatibility, `fill: true` (default) is equivalent to `fill: 'origin'`
+ +**Example** +```javascript +new Chart(ctx, { + data: { + datasets: [ + {fill: 'origin'}, // 0: fill to 'origin' + {fill: '+2'}, // 1: fill to dataset 3 + {fill: 1}, // 2: fill to dataset 1 + {fill: false}, // 3: no fill + {fill: '-2'} // 4: fill to dataset 2 + ] + } +}) +``` + +## Configuration +| Option | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| [`plugins.filler.propagate`](#propagate) | `Boolean` | `true` | Fill propagation when target is hidden + +### propagate +Boolean (default: `true`) + +If `true`, the fill area will be recursively extended to the visible target defined by the `fill` value of hidden dataset targets: + +**Example** +```javascript +new Chart(ctx, { + data: { + datasets: [ + {fill: 'origin'}, // 0: fill to 'origin' + {fill: '-1'}, // 1: fill to dataset 0 + {fill: 1}, // 2: fill to dataset 1 + {fill: false}, // 3: no fill + {fill: '-2'} // 4: fill to dataset 2 + ] + }, + options: { + plugins: { + filler: { + propagate: true + } + } + } +}) +``` + +`propagate: true`: +- if dataset 2 is hidden, dataset 4 will fill to dataset 1 +- if dataset 2 and 1 are hidden, dataset 4 will fill to `'origin'` + +`propagate: false`: +- if dataset 2 and/or 4 are hidden, dataset 4 will not be filled diff --git a/docs/charts/line.md b/docs/charts/line.md index a64f436cfdb..ba7911fe798 100644 --- a/docs/charts/line.md +++ b/docs/charts/line.md @@ -56,7 +56,7 @@ All point* properties can be specified as an array. If these are set to an array | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) | `cubicInterpolationMode` | `String` | Algorithm used to interpolate a smooth curve from the discrete data points. [more...](#cubicInterpolationMode) -| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill) +| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md) | `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. | `pointBackgroundColor` | `Color/Color[]` | The fill color for points. | `pointBorderColor` | `Color/Color[]` | The border color for points. @@ -77,20 +77,12 @@ The following interpolation modes are supported: * 'default' * 'monotone'. -The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. +The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. -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. +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. If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used. -### fill -If `true`, fill the area under the line. The line is filled to the baseline. If the y axis has a 0 value, the line is filled to that point. If the axis has only negative values, the line is filled to the highest value. If the axis has only positive values, it is filled to the lowest value. - -String values to fill to specific locations are: -* `'zero'` -* `'top'` -* `'bottom'` - ### pointStyle The style of point. Options are: * 'circle' @@ -246,4 +238,4 @@ new Chart(ctx, { responsiveAnimationDuration: 0, // animation duration after a resize } }); -``` \ No newline at end of file +``` diff --git a/docs/charts/radar.md b/docs/charts/radar.md index 4728ad7771d..dd5d47b27e4 100644 --- a/docs/charts/radar.md +++ b/docs/charts/radar.md @@ -76,8 +76,8 @@ All point* properties can be specified as an array. If these are set to an array | `borderDashOffset` | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill) -| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. +| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md) +| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. | `pointBackgroundColor` | `Color/Color[]` | The fill color for points. | `pointBorderColor` | `Color/Color[]` | The border color for points. | `pointBorderWidth` | `Number/Number[]` | The width of the point border in pixels. @@ -142,4 +142,4 @@ data: { data: [20, 10, 4, 2] }] } -``` \ No newline at end of file +``` diff --git a/docs/style.css b/docs/style.css index 89e7c705355..acdd3e5e946 100644 --- a/docs/style.css +++ b/docs/style.css @@ -9,3 +9,7 @@ a.anchorjs-link { a.anchorjs-link:hover { color: rgba(65, 131, 196, 1); } + +sup { + font-size: 0.75em !important; +}