From 3a127bb2c98fcf970c6689aa65fd0869dc77e907 Mon Sep 17 00:00:00 2001 From: sbosse Date: Mon, 21 Jul 2025 23:35:22 +0200 Subject: [PATCH] Mon 21 Jul 22:43:21 CEST 2025 --- js/ui/chart/docs/configuration/elements.md | 87 ++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 js/ui/chart/docs/configuration/elements.md diff --git a/js/ui/chart/docs/configuration/elements.md b/js/ui/chart/docs/configuration/elements.md new file mode 100644 index 0000000..a2a794d --- /dev/null +++ b/js/ui/chart/docs/configuration/elements.md @@ -0,0 +1,87 @@ +# Elements + +While chart types provide settings to configure the styling of each dataset, you sometimes want to style **all datasets the same way**. A common example would be to stroke all of the bars in a bar chart with the same colour but change the fill per dataset. Options can be configured for four different types of elements: **[arc](#arc-configuration)**, **[lines](#line-configuration)**, **[points](#point-configuration)**, and **[rectangles](#rectangle-configuration)**. When set, these options apply to all objects of that type unless specifically overridden by the configuration attached to a dataset. + +## Global Configuration + +The element options can be specified per chart or globally. The global options for elements are defined in `Chart.defaults.global.elements`. For example, to set the border width of all bar charts globally you would do: + +```javascript +Chart.defaults.global.elements.rectangle.borderWidth = 2; +``` + +## Point Configuration +Point elements are used to represent the points in a line, radar or bubble chart. + +Global point options: `Chart.defaults.global.elements.point`. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `radius` | `number` | `3` | Point radius. +| [`pointStyle`](#point-styles) | string|Image | `'circle'` | Point style. +| `rotation` | `number` | `0` | Point rotation (in degrees). +| `backgroundColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Point fill color. +| `borderWidth` | `number` | `1` | Point stroke width. +| `borderColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Point stroke color. +| `hitRadius` | `number` | `1` | Extra radius added to point radius for hit detection. +| `hoverRadius` | `number` | `4` | Point radius when hovered. +| `hoverBorderWidth` | `number` | `1` | Stroke width when hovered. + +### Point Styles + +The following values are supported: +- `'circle'` +- `'cross'` +- `'crossRot'` +- `'dash'` +- `'line'` +- `'rect'` +- `'rectRounded'` +- `'rectRot'` +- `'star'` +- `'triangle'` + +If the value is an image, that image is drawn on the canvas using [drawImage](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/drawImage). + +## Line Configuration +Line elements are used to represent the line in a line chart. + +Global line options: `Chart.defaults.global.elements.line`. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `tension` | `number` | `0.4` | Bézier curve tension (`0` for no Bézier curves). +| `backgroundColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Line fill color. +| `borderWidth` | `number` | `3` | Line stroke width. +| `borderColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Line stroke color. +| `borderCapStyle` | `string` | `'butt'` | Line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap). +| `borderDash` | `number[]` | `[]` | Line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| `borderDashOffset` | `number` | `0.0` | Line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| `borderJoinStyle` | `string` | `'miter'` | Line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| `capBezierPoints` | `boolean` | `true` | `true` to keep Bézier control inside the chart, `false` for no restriction. +| `fill` | boolean|string | `true` | Fill location: `'zero'`, `'top'`, `'bottom'`, `true` (eq. `'zero'`) or `false` (no fill). +| `stepped` | `boolean` | `false` | `true` to show the line as a stepped line (`tension` will be ignored). + +## Rectangle Configuration +Rectangle elements are used to represent the bars in a bar chart. + +Global rectangle options: `Chart.defaults.global.elements.rectangle`. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `backgroundColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Bar fill color. +| `borderWidth` | `number` | `0` | Bar stroke width. +| `borderColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Bar stroke color. +| `borderSkipped` | `string` | `'bottom'` | Skipped (excluded) border: `'bottom'`, `'left'`, `'top'` or `'right'`. + +## Arc Configuration +Arcs are used in the polar area, doughnut and pie charts. + +Global arc options: `Chart.defaults.global.elements.arc`. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `backgroundColor` | `Color` | `'rgba(0, 0, 0, 0.1)'` | Arc fill color. +| `borderAlign` | `string` | `'center'` | Arc stroke alignment. +| `borderColor` | `Color` | `'#fff'` | Arc stroke color. +| `borderWidth`| `number` | `2` | Arc stroke width.