diff --git a/docs/charts/bar.md b/docs/charts/bar.md index d2ea8ba45d6..d4d0a271fdf 100644 --- a/docs/charts/bar.md +++ b/docs/charts/bar.md @@ -53,52 +53,77 @@ module.exports = { }; ``` -## Example Usage +## Dataset Properties -```javascript -var myBarChart = new Chart(ctx, { - type: 'bar', - data: data, - options: options -}); -``` +Namespaces: -## Dataset Properties +* `data.datasets[index]` - options for this dataset only +* `options.datasets.bar` - options for all bar datasets +* `options.elements.bar` - options for all [bar elements](../configuration/elements.md#bar-configuration) +* `options` - options for the whole chart The bar 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 color of the bars is generally set this way. +Only the `data` option needs to be specified in the dataset namespace. | Name | Type | [Scriptable](../general/options.md#scriptable-options) | [Indexable](../general/options.md#indexable-options) | Default | ---- | ---- | :----: | :----: | ---- | [`backgroundColor`](#styling) | [`Color`](../general/colors.md) | Yes | Yes | `'rgba(0, 0, 0, 0.1)'` | [`base`](#general) | `number` | Yes | Yes | +| [`barPercentage`](#barpercentage) | `number` | - | - | `0.9` | +| [`barThickness`](#barthickness) | `number`\|`string` | - | - | | | [`borderColor`](#styling) | [`Color`](../general/colors.md) | Yes | Yes | `'rgba(0, 0, 0, 0.1)'` | [`borderSkipped`](#borderskipped) | `string` | Yes | Yes | `'start'` | [`borderWidth`](#borderwidth) | `number`\|`object` | Yes | Yes | `0` | [`borderRadius`](#borderradius) | `number`\|`object` | Yes | Yes | `0` -| [`clip`](#general) | `number`\|`object` | - | - | `undefined` -| [`data`](#data-structure) | `object`\|`object[]`\|`number[]`\|`string[]` | - | - | **required** -| [`hoverBackgroundColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined` -| [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined` +| [`categoryPercentage`](#categorypercentage) | `number` | - | - | `0.8` | +| [`clip`](#general) | `number`\|`object` | - | - | +| [`data`](#data-structure) | `object`\|`object[]`\| `number[]`\|`string[]` | - | - | **required** +| [`grouped`](#general) | `boolean` | - | - | `true` | +| [`hoverBackgroundColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | +| [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | | [`hoverBorderWidth`](#interactions) | `number` | Yes | Yes | `1` | [`hoverBorderRadius`](#interactions) | `number` | Yes | Yes | `0` | [`indexAxis`](#general) | `string` | - | - | `'x'` +| [`maxBarThickness`](#maxbarthickness) | `number` | - | - | | +| [`minBarLength`](#styling) | `number` | - | - | | | [`label`](#general) | `string` | - | - | `''` | [`order`](#general) | `number` | - | - | `0` | [`pointStyle`](../configuration/elements.md#point-styles) | `string`\|`Image` | Yes | - | `'circle'` +| [`skipNull`](#general) | `boolean` | - | - | | +| [`stack`](#general) | `string` | - | - | `'bar'` | | [`xAxisID`](#general) | `string` | - | - | first x axis | [`yAxisID`](#general) | `string` | - | - | first y axis +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + +### Example dataset configuration + +```javascript +data: { + datasets: [{ + barPercentage: 0.5, + barThickness: 6, + maxBarThickness: 8, + minBarLength: 2, + data: [10, 20, 30, 40, 50, 60, 70] + }] +}; +``` + ### General | Name | Description | ---- | ---- | `base` | Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value. | `clip` | How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. `0` = clip at chartArea. Clipping can also be configured per side: `clip: {left: 5, top: false, right: -2, bottom: 0}` +| `grouped` | Should the bars be grouped on index axis. When `true`, all the datasets at same index value will be placed next to each other centering on that index value. When `false`, each bar is placed on its actual index-axis value. | `indexAxis` | The base axis of the dataset. `'x'` for vertical bars and `'y'` for horizontal bars. | `label` | The label for the dataset which appears in the legend and tooltips. | `order` | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| `skipNull` | If `true`, null or undefined values will not be used for spacing calculations when determining bar size. +| `stack` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). [more](#stacked-bar-charts) | `xAxisID` | The ID of the x-axis to plot this dataset on. | `yAxisID` | The ID of the y-axis to plot this dataset on. @@ -113,6 +138,7 @@ The style of each bar can be controlled with the following properties: | [`borderSkipped`](#borderskipped) | The edge to skip when drawing bar. | [`borderWidth`](#borderwidth) | The bar border width (in pixels). | [`borderRadius`](#borderradius) | The bar border radius (in pixels). +| `minBarLength` | Set this to ensure that bars have a minimum length in pixels. | `pointStyle` | Style of the point for legend. [more...](../configuration/elements.md#point-styles) All these values, if `undefined`, fallback to the associated [`elements.bar.*`](../configuration/elements.md#bar-configuration) options. @@ -158,33 +184,13 @@ The interaction with each bar can be controlled with the following properties: All these values, if `undefined`, fallback to the associated [`elements.bar.*`](../configuration/elements.md#bar-configuration) options. -## Dataset Configuration +### barPercentage -The bar chart accepts the following configuration from the associated dataset options: +Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. [more...](#barpercentage-vs-categorypercentage) -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `barPercentage` | `number` | `0.9` | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. [more...](#barpercentage-vs-categorypercentage) -| `categoryPercentage` | `number` | `0.8` | Percent (0-1) of the available width each category should be within the sample width. [more...](#barpercentage-vs-categorypercentage) -| `barThickness` | `number`\|`string` | | Manually set width of each bar in pixels. If set to `'flex'`, it computes "optimal" sample widths that globally arrange bars side by side. If not set (default), bars are equally sized based on the smallest interval. [more...](#barthickness) -| `base` | `number` | | Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value. -| `grouped` | `boolean` | `true` | Should the bars be grouped on index axis. When `true`, all the datasets at same index value will be placed next to each other centering on that index value. When `false`, each bar is placed on its actual index-axis value. -| `maxBarThickness` | `number` | | Set this to ensure that bars are not sized thicker than this. -| `minBarLength` | `number` | | Set this to ensure that bars have a minimum length in pixels. +### categoryPercentage -### Example dataset configuration - -```javascript -data: { - datasets: [{ - barPercentage: 0.5, - barThickness: 6, - maxBarThickness: 8, - minBarLength: 2, - data: [10, 20, 30, 40, 50, 60, 70] - }] -}; -``` +Percent (0-1) of the available width each category should be within the sample width. [more...](#barpercentage-vs-categorypercentage) ### barThickness @@ -194,13 +200,9 @@ If set to `'flex'`, the base sample widths are calculated automatically based on If not set (default), the base sample widths are calculated using the smallest interval that prevents bar overlapping, and bars are sized using `barPercentage` and `categoryPercentage`. This mode always generates bars equally sized. -## Config Options +### maxBarThickness -These are the customisation options specific to Bar charts. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart. - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `skipNull` | `boolean` | `undefined` | If `true`, null or undefined values will not be drawn +Set this to ensure that bars are not sized thicker than this. ## Scale Configuration @@ -282,12 +284,6 @@ var stackedBar = new Chart(ctx, { }); ``` -The following dataset properties are specific to stacked bar charts. - -| Name | Type | Description -| ---- | ---- | ----------- -| `stack` | `string` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). Defaults to `bar`. - ## Horizontal Bar Chart A horizontal bar chart is a variation on a vertical bar chart. It is sometimes used to show trend data, and the comparison of multiple data sets side by side. diff --git a/docs/charts/bubble.md b/docs/charts/bubble.md index 94ebbe37ace..ef29ad2a1c5 100644 --- a/docs/charts/bubble.md +++ b/docs/charts/bubble.md @@ -25,6 +25,7 @@ const data = { const config = { type: 'bubble', data: data, + options: {} }; // @@ -34,18 +35,14 @@ module.exports = { }; ``` -## Example Usage +## Dataset Properties -```javascript -// For a bubble chart -var myBubbleChart = new Chart(ctx, { - type: 'bubble', - data: data, - options: options -}); -``` +Namespaces: -## Dataset Properties +* `data.datasets[index]` - options for this dataset only +* `options.datasets.bubble` - options for all bubble datasets +* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration) +* `options` - options for the whole chart The bubble 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 the bubbles is generally set this way. @@ -67,6 +64,8 @@ The bubble chart allows a number of properties to be specified for each dataset. | [`rotation`](#styling) | `number` | Yes | Yes | `0` | [`radius`](#styling) | `number` | Yes | Yes | `3` +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + ### General | Name | Description diff --git a/docs/charts/doughnut.md b/docs/charts/doughnut.md index 66c31125c15..a4f36794f85 100644 --- a/docs/charts/doughnut.md +++ b/docs/charts/doughnut.md @@ -90,6 +90,14 @@ module.exports = { ## Dataset Properties +Namespaces: + +* `data.datasets[index]` - options for this dataset only +* `options.datasets.doughnut` - options for all doughnut datasets +* `options.datasets.pie` - options for all pie datasets +* `options.elements.arc` - options for all [arc elements](../configuration/elements.md#arc-configuration) +* `options` - options for the whole chart + The doughnut/pie 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 colours of the dataset's arcs are generally set this way. | Name | Type | [Scriptable](../general/options.md#scriptable-options) | [Indexable](../general/options.md#indexable-options) | Default @@ -110,6 +118,8 @@ The doughnut/pie chart allows a number of properties to be specified for each da | [`rotation`](#general) | `number` | - | - | `undefined` | [`weight`](#styling) | `number` | - | - | `1` +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + ### General | Name | Description diff --git a/docs/charts/line.md b/docs/charts/line.md index f9a687551d5..c04290cab44 100644 --- a/docs/charts/line.md +++ b/docs/charts/line.md @@ -30,17 +30,15 @@ module.exports = { }; ``` -## Example Usage +## Dataset Properties -```javascript -var myLineChart = new Chart(ctx, { - type: 'line', - data: data, - options: options -}); -``` +Namespaces: -## Dataset Properties +* `data.datasets[index]` - options for this dataset only +* `options.datasets.line` - options for all line datasets +* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration) +* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration) +* `options` - options for the whole chart 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. @@ -54,7 +52,7 @@ The line chart allows a number of properties to be specified for each dataset. T | [`borderJoinStyle`](#line-styling) | `string` | Yes | - | `'miter'` | [`borderWidth`](#line-styling) | `number` | Yes | - | `3` | [`clip`](#general) | `number`\|`object` | - | - | `undefined` -| [`data`](#data-structure) | `object`\|`object[]`\|`number[]`\|`string[]` | - | - | **required** +| [`data`](#data-structure) | `object`\|`object[]`\| `number[]`\|`string[]` | - | - | **required** | [`cubicInterpolationMode`](#cubicinterpolationmode) | `string` | Yes | - | `'default'` | [`fill`](#line-styling) | `boolean`\|`string` | Yes | - | `false` | [`hoverBackgroundColor`](#line-styling) | [`Color`](../general/colors.md) | Yes | - | `undefined` @@ -81,10 +79,13 @@ The line chart allows a number of properties to be specified for each dataset. T | [`pointStyle`](#point-styling) | `string`\|`Image` | Yes | Yes | `'circle'` | [`showLine`](#line-styling) | `boolean` | - | - | `true` | [`spanGaps`](#line-styling) | `boolean`\|`number` | - | - | `undefined` +| [`stack`](#general) | `string` | - | - | `'line'` | | [`stepped`](#stepped) | `boolean`\|`string` | - | - | `false` | [`xAxisID`](#general) | `string` | - | - | first x axis | [`yAxisID`](#general) | `string` | - | - | first y axis +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + ### General | Name | Description @@ -93,6 +94,7 @@ The line chart allows a number of properties to be specified for each dataset. T | `indexAxis` | The base axis of the dataset. `'x'` for horizontal lines and `'y'` for vertical lines. | `label` | The label for the dataset which appears in the legend and tooltips. | `order` | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| `stack` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). [more](#stacked-area-charts) | `xAxisID` | The ID of the x-axis to plot this dataset on. | `yAxisID` | The ID of the y-axis to plot this dataset on. @@ -168,15 +170,6 @@ The following values are supported for `stepped`. If the `stepped` value is set to anything other than false, `tension` will be ignored. -## Configuration Options - -The line chart defines the following configuration options. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart. - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `showLine` | `boolean` | `true` | If false, the lines between points are not drawn. -| `spanGaps` | `boolean`\|`number` | `false` | If true, lines will be drawn between points with no or null data. If false, points with `null` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. - ## Default Options It is common to want to apply a configuration setting to all created line charts. The global line chart settings are stored in `Chart.overrides.line`. Changing the global options only affects charts created after the change. Existing charts are not changed. @@ -269,18 +262,6 @@ module.exports = { }; ``` -## Example - -```javascript -var myLineChart = new Chart(ctx, { - type: 'line', - data: data, - options: { - indexAxis: 'y' - } -}); -``` - ### Config Options The configuration options for the vertical line chart are the same as for the [line chart](#configuration-options). However, any options specified on the x-axis in a line chart, are applied to the y-axis in a vertical line chart. diff --git a/docs/charts/polar.md b/docs/charts/polar.md index cf41a1a2531..550674272d2 100644 --- a/docs/charts/polar.md +++ b/docs/charts/polar.md @@ -32,6 +32,7 @@ const data = { const config = { type: 'polarArea', data: data, + options: {} }; // @@ -41,17 +42,14 @@ module.exports = { }; ``` -## Example Usage +## Dataset Properties -```javascript -new Chart(ctx, { - data: data, - type: 'polarArea', - options: options -}); -``` +Namespaces: -## Dataset Properties +* `data.datasets[index]` - options for this dataset only +* `options.datasets.polarArea` - options for all polarArea datasets +* `options.elements.arc` - options for all [arc elements](../configuration/elements.md#arc-configuration) +* `options` - options for the whole chart The following options can be included in a polar area chart dataset to configure options for that specific dataset. @@ -67,6 +65,8 @@ The following options can be included in a polar area chart dataset to configure | [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined` | [`hoverBorderWidth`](#interactions) | `number` | Yes | Yes | `undefined` +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + ### General | Name | Description diff --git a/docs/charts/radar.md b/docs/charts/radar.md index fe2d7427abb..8aecced8945 100644 --- a/docs/charts/radar.md +++ b/docs/charts/radar.md @@ -60,19 +60,15 @@ module.exports = { }; ``` - +## Dataset Properties -## Example Usage +Namespaces: -```javascript -var myRadarChart = new Chart(ctx, { - type: 'radar', - data: data, - options: options -}); -``` - -## Dataset Properties +* `data.datasets[index]` - options for this dataset only +* `options.datasets.line` - options for all line datasets +* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration) +* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration) +* `options` - options for the whole chart The radar 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. @@ -111,6 +107,8 @@ The radar chart allows a number of properties to be specified for each dataset. | [`pointStyle`](#point-styling) | `string`\|`Image` | Yes | Yes | `'circle'` | [`spanGaps`](#line-styling) | `boolean` | - | - | `undefined` +All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options) + ### General | Name | Description @@ -165,14 +163,6 @@ The interaction with each point can be controlled with the following properties: | `pointHoverBorderWidth` | Border width of point when hovered. | `pointHoverRadius` | The radius of the point when hovered. -## Configuration Options - -The radar chart defines the following configuration options. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart. - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `spanGaps` | `boolean` | `false` | If false, `null` data causes a break in the line. - ## Scale Options The radar chart supports only a single scale. The options for this scale are defined in the `scale` property. diff --git a/docs/charts/scatter.md b/docs/charts/scatter.md index 918995d8d36..1c2462f4bcb 100644 --- a/docs/charts/scatter.md +++ b/docs/charts/scatter.md @@ -48,6 +48,14 @@ module.exports = { ## Dataset Properties +Namespaces: + +* `data.datasets[index]` - options for this dataset only +* `options.datasets.scatter` - options for all scatter datasets +* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration) +* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration) +* `options` - options for the whole chart + The scatter chart supports all of the same properties as the [line chart](./charts/line.md#dataset-properties). By default, the scatter chart will override the showLine property of the line chart to `false`.