If set, the scale ticks will be enumerated by multiple of `stepSize`, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm.
-This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`.
+This example sets up a chart with a y-axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`.
```javascript
let options = {
In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/).
-Scales in Chart.js >v2.0 are significantly more powerful, but also different than those of v1.0.
+Scales in Chart.js >v2.0 are significantly more powerful, but also different from those of v1.0.
* Multiple X & Y axes are supported.
-* A built-in label auto-skip feature detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally.
+* A built-in label auto-skip feature detects would-be overlapping ticks and labels and removes every nth label to keep things displayed normally.
* Scale titles are supported.
* New scale types can be extended without writing an entirely new chart type.
## Default scales
-The default `scaleId`'s for carterian charts are `'x'` and `'y'`. For radial charts: `'r'`.
-Each dataset is mapped to a scale for each axis (x, y or r) it requires. The scaleId's that a dataset is mapped to, is determined by the `xAxisID`, `yAxisID` or `rAxisID`.
-If the ID for an axis is not specified, first scale for that axis is used. If no scale for an axis is found, a new scale is created.
+The default `scaleId`'s for cartesian charts are `'x'` and `'y'`. For radial charts: `'r'`.
+Each dataset is mapped to a scale for each axis (x, y or r) it requires. The scaleId's that a dataset is mapped to is determined by the `xAxisID`, `yAxisID` or `rAxisID`.
+If the ID for an axis is not specified, the first scale for that axis is used. If no scale for an axis is found, a new scale is created.
Some examples:
## Common Configuration
:::tip Note
-These are only the common options supported by all axes. Please see specific axis documentation for all of the available options for that axis.
+These are only the common options supported by all axes. Please see specific axis documentation for all the available options for that axis.
:::
!!!include(axes/_common.md)!!!
## Tick Configuration
:::tip Note
-These are only the common tick options supported by all axes. Please see specific axis documentation for all of the available tick options for that axis.
+These are only the common tick options supported by all axes. Please see specific axis documentation for all the available tick options for that axis.
:::
!!!include(axes/_common_ticks.md)!!!
Given the number of axis range settings, it is important to understand how they all interact with each other.
-The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behaviour.
+The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto-fit behaviour.
```javascript
let minDataValue = Math.min(mostNegativeValue, options.suggestedMin);
## Stacking
-By default data is not stacked. If the `stacked` option of the value scale (y-axis on horizontal chart) is `true`, positive and negative values are stacked separately. Additionally a `stack` option can be defined per dataset to further divide into stack groups [more...](../general/data-structures/#dataset-configuration).
+By default, data is not stacked. If the `stacked` option of the value scale (y-axis on horizontal chart) is `true`, positive and negative values are stacked separately. Additionally, a `stack` option can be defined per dataset to further divide into stack groups [more...](../general/data-structures/#dataset-configuration).
For some charts, you might want to stack positive and negative values together. That can be achieved by specifying `stacked: 'single'`.
## Callbacks
| `pointLabels` | `object` | | Point label configuration. [more...](#point-label-options)
| `startAngle` | `number` | `0` | Starting angle of the scale. In degrees, 0 is at top.
-### Common options to all axes
+### Common options for all axes
Namespace: `options.scales[scaleId]`
Given the number of axis range settings, it is important to understand how they all interact with each other.
-The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behaviour.
+The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto-fit behaviour.
```javascript
let minDataValue = Math.min(mostNegativeValue, options.ticks.suggestedMin);
## Data Structure
-All of the supported [data structures](../general/data-structures.md) can be used with bar charts.
+All the supported [data structures](../general/data-structures.md) can be used with bar charts.
## Stacked Bar Chart
## 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.
-To achieve this you will have to set the `indexAxis` property in the options object to `'y'`.
+To achieve this, you will have to set the `indexAxis` property in the options object to `'y'`.
The default for this property is `'x'` and thus will show vertical bars.
```js chart-editor
## Data Structure
-For a pie chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each.
+For a pie chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all the numbers and calculate the relative proportion of each.
You also need to specify an array of labels so that tooltips appear correctly.
### Segment
-Line segment styles can be overridden by scriptable options in the `segment` object. Currently all of the `border*` and `backgroundColor` options are supported. The segment styles are resolved for each section of the line between each point. `undefined` fallbacks to main line styles.
+Line segment styles can be overridden by scriptable options in the `segment` object. Currently, all of the `border*` and `backgroundColor` options are supported. The segment styles are resolved for each section of the line between each point. `undefined` fallbacks to main line styles.
:::tip
To be able to style gaps, you need the [`spanGaps`](#line-styling) option enabled.
## Data Structure
-All of the supported [data structures](../general/data-structures.md) can be used with line charts.
+All the supported [data structures](../general/data-structures.md) can be used with line charts.
## Stacked Area Chart
## Vertical Line Chart
A vertical line chart is a variation on the horizontal line chart.
-To achieve this you will have to set the `indexAxis` property in the options object to `'y'`.
+To achieve this, you will have to set the `indexAxis` property in the options object to `'y'`.
The default for this property is `'x'` and thus will show horizontal lines.
```js chart-editor
# Scatter Chart
-Scatter charts are based on basic line charts with the x axis changed to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. The example below creates a scatter chart with 4 points.
+Scatter charts are based on basic line charts with the x-axis changed to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. The example below creates a scatter chart with 4 points.
```js chart-editor
// <block:setup:1>
* `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](./line.md#dataset-properties).
+The scatter chart supports all the same properties as the [line chart](./line.md#dataset-properties).
By default, the scatter chart will override the showLine property of the line chart to `false`.
-The index scale is of the type `linear`. This means if you are using the labels array the values have to be numbers or parsable to numbers, the same applies to the object format for the keys.
+The index scale is of the type `linear`. This means, if you are using the labels array, the values have to be numbers or parsable to numbers, the same applies to the object format for the keys.
## Data Structure
});
```
-Another example usage of these callbacks can be found [in this progress bar sample.](../samples/advanced/progress-bar.md) which displays a progress bar showing how far along the animation is.
+Another example usage of these callbacks can be found [in this progress bar sample,](../samples/advanced/progress-bar.md) which displays a progress bar showing how far along the animation is.
# Device Pixel Ratio
-By default the chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g. Retina displays).
+By default, the chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g. Retina displays).
-For applications where a chart will be converted to a bitmap, or printed to a higher DPI medium it can be desirable to render the chart at a higher resolution than the default.
+For applications where a chart will be converted to a bitmap, or printed to a higher DPI medium, it can be desirable to render the chart at a higher resolution than the default.
Setting `devicePixelRatio` to a value other than 1 will force the canvas size to be scaled by that amount, relative to the container size. There should be no visible difference on screen; the difference will only be visible when the image is zoomed or printed.
# 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 **[bars](#bar-configuration)**. When set, these options apply to all objects of that type unless specifically overridden by the configuration attached to a dataset.
+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 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 **[bars](#bar-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.elements`. For example, to set the border width of all bar charts globally you would do:
+The element options can be specified per chart or globally. The global options for elements are defined in `Chart.defaults.elements`. For example, to set the border width of all bar charts globally, you would do:
```javascript
Chart.defaults.elements.bar.borderWidth = 2;
```javascript
const config = {
- type: 'line'
- data: {}
- options: {}
+ type: 'line',
+ data: {},
+ options: {},
plugins: []
}
```
This concept was introduced in Chart.js 1.0 to keep configuration [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and allow for changing options globally across chart types, avoiding the need to specify options for each instance, or the default for a particular chart type.
-Chart.js merges the options object passed to the chart with the global configuration using chart type defaults and scales defaults appropriately. This way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. The global general options are defined in `Chart.defaults`. The defaults for each chart type are discussed in the documentation for that chart type.
+Chart.js merges the `options` object passed to the chart with the global configuration using chart type defaults and scales defaults appropriately. This way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. The global general options are defined in `Chart.defaults`. The defaults for each chart type are discussed in the documentation for that chart type.
The following example would set the interaction mode to 'nearest' for all charts where this was not overridden by the chart type defaults or the options passed to the constructor on creation.
## Example
-The following example will create a chart with the legend enabled and turn all of the text red in color.
+The following example will create a chart with the legend enabled and turn all the text red in color.
```javascript
const chart = new Chart(ctx, {
}
```
-Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.
+Let's say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.
```javascript
const defaultLegendClickHandler = Chart.defaults.plugins.legend.onClick;
with all present components separated by hyphens.
-By default the chart is using the default locale of the platform which is running on.
+By default, the chart is using the default locale of the platform which is running on.
## Configuration Options
# Responsive Charts
-When it comes to changing the chart size based on the window size, a major limitation is that the canvas *render* size (`canvas.width` and `.height`) can **not** be expressed with relative values, contrary to the *display* size (`canvas.style.width` and `.height`). Furthermore, these sizes are independent from each other and thus the canvas *render* size does not adjust automatically based on the *display* size, making the rendering inaccurate.
+When it comes to changing the chart size based on the window size, a major limitation is that the canvas *render* size (`canvas.width` and `.height`) can **not** be expressed with relative values, contrary to the *display* size (`canvas.style.width` and `.height`). Furthermore, these sizes are independent of each other and thus the canvas *render* size does not adjust automatically based on the *display* size, making the rendering inaccurate.
The following examples **do not work**:
### Label Point Style Callback
-For example, to draw triangles instead of the regular color box for each item in the tooltip you could do:
+For example, to draw triangles instead of the regular color box for each item in the tooltip, you could do:
```javascript
const chart = new Chart(ctx, {
## getVisibleDatasetCount
-Returns the amount of datasets that are currently not hidden.
+Returns the number of datasets that are currently not hidden.
```javascript
const numberOfVisibleDatasets = chart.getVisibleDatasetCount();
## getDataVisibility(index)
-Returns the stored visibility state of an data index for all datasets. Set by [toggleDataVisibility](#toggleDataVisibility). A dataset controller should use this method to determine if an item should not be visible.
+Returns the stored visibility state of a data index for all datasets. Set by [toggleDataVisibility](#toggleDataVisibility). A dataset controller should use this method to determine if an item should not be visible.
```javascript
const visible = chart.getDataVisibility(2);
## Extending Existing Chart Types
-Extending or replacing an existing controller type is easy. Simply replace the constructor for one of the built in types with your own.
+Extending or replacing an existing controller type is easy. Simply replace the constructor for one of the built-in types with your own.
-The built in controller types are:
+The built-in controller types are:
* `BarController`
* `BubbleController`
- Consider whether your changes are useful for all users, or if creating a Chart.js [plugin](plugins.md) would be more appropriate.
- Check that your code will pass tests and `eslint` code standards. `pnpm test` will run both the linter and tests for you.
- Add unit tests and document new functionality (in the `test/` and `docs/` directories respectively).
-- Avoid breaking changes unless there is an upcoming major release, which is infrequent. We encourage people to write plugins for most new advanced features, and care a lot about backward compatibility.
+- Avoid breaking changes unless there is an upcoming major release, which is infrequent. We encourage people to write plugins for the most new advanced features, and care a lot about backward compatibility.
- We strongly prefer new methods to be added as private whenever possible. A method can be made private either by making a top-level `function` outside of a class or by prefixing it with `_` and adding `@private` JSDoc if inside a class. Public APIs take considerable time to review and become locked once implemented as we have limited ability to change them without breaking backward compatibility. Private APIs allow the flexibility to address unforeseen cases.
## Joining the project
- Add a [describe line](https://github.com/chartjs/Chart.js/blob/4b421a50bfa17f73ac7aa8db7d077e674dbc148d/test/specs/plugin.filler.tests.js#L10) to the beginning of `test/specs/{spec.name}.tests.js` if it doesn't exist yet.
- Run `pnpm run dev`.
- Click the *"Debug"* button (top/right): a test should fail with the associated canvas visible.
-- Right click on the chart and *"Save image as..."* `test/fixtures/{spec.name}/{feature-name}.png` making sure not to activate the tooltip or any hover functionality
+- Right-click on the chart and *"Save image as..."* `test/fixtures/{spec.name}/{feature-name}.png` making sure not to activate the tooltip or any hover functionality
- Refresh the browser page (`CTRL+R`): test should now pass
- Verify test relevancy by changing the feature values *slightly* in the JSON file.
Please report these on the GitHub page - at <a href="https://github.com/chartjs/Chart.js" target="_blank">github.com/chartjs/Chart.js</a>. Please do not use issues for support requests. For help using Chart.js, please take a look at the [`chart.js`](https://stackoverflow.com/questions/tagged/chart.js) tag on Stack Overflow.
-Well structured, detailed bug reports are hugely valuable for the project.
+Well-structured, detailed bug reports are hugely valuable for the project.
Guidelines for reporting bugs:
## Latest resources
-Latest documentation and samples, including unreleased features, are available at:
+The latest documentation and samples, including unreleased features, are available at:
- <https://www.chartjs.org/docs/master/>
- <https://www.chartjs.org/samples/master/>
## Updating Options
-To update the options, mutating the options property in place or passing in a new options object are supported.
+To update the options, mutating the `options` property in place or passing in a new options object are supported.
- If the options are mutated in place, other option properties would be preserved, including those calculated by Chart.js.
- If created as a new object, it would be like creating a new chart with the options - old options would be discarded.
}
```
-You can also update a specific scale either by its id.
+You can update a specific scale by its id as well.
```javascript
function updateScale(chart) {
### Dynamic datasets at runtime
-By default the colors plugin only works when you initialize the chart without any colors for the border or background specified.
-If you want to force the colors plugin to always color your datasets, for example when using dynamic datasets at runtime you will need to set the `forceOverride` option to true:
+By default, the colors plugin only works when you initialize the chart without any colors for the border or background specified.
+If you want to force the colors plugin to always color your datasets, for example, when using dynamic datasets at runtime you will need to set the `forceOverride` option to true:
```js
const options = {
```
:::warning
-When using object notation in a radar chart you still need a labels array with labels for the chart to show correctly.
+When using object notation in a radar chart, you still need a labels array with labels for the chart to show correctly.
:::
## Object
# Fonts
-There are special global settings that can change all of the fonts on the chart. These options are in `Chart.defaults.font`. The global font settings only apply when more specific options are not included in the config.
+There are special global settings that can change all the fonts on the chart. These options are in `Chart.defaults.font`. The global font settings only apply when more specific options are not included in the config.
-For example, in this chart the text will have a font size of 16px except for the labels in the legend.
+For example, in this chart, the text will have a font size of 16px except for the labels in the legend.
```javascript
Chart.defaults.font.size = 16;
In addition to [chart](#chart)
-* `active`: true if element is active (hovered)
+* `active`: true if an element is active (hovered)
* `dataset`: dataset at index `datasetIndex`
* `datasetIndex`: index of the current dataset
* `index`: same as `datasetIndex`
In addition to [dataset](#dataset)
-* `active`: true if element is active (hovered)
+* `active`: true if an element is active (hovered)
* `dataIndex`: index of the current data
* `parsed`: the parsed data values for the given `dataIndex` and `datasetIndex`
* `raw`: the raw data values for the given `dataIndex` and `datasetIndex`
If this value is a number, it is applied to all sides (left, top, right, bottom).
-For example, defining a 20px padding to all sides of chart:
+For example, defining a 20px padding to all sides of the chart:
```javascript
let chart = new Chart(ctx, {
## {top, left, bottom, right} object
-If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top` and `bottom` properties can also be specified.
+If this value is an object, the `left` property defines the left padding. Similarly, the `right`, `top` and `bottom` properties can also be specified.
Omitted properties default to `0`.
Let's say you wanted to add 50px of padding to the left side of the chart canvas, you would do:
### Canvas rendering
-Chart.js renders chart elements on an HTML5 canvas unlike several other, mostly D3.js-based, charting libraries that render as SVG. Canvas rendering makes Chart.js very performant, especially for large datasets and complex visualizations that would otherwise require thousands of SVG nodes in the DOM tree. At the same time, canvas rendering disallows CSS styling, so you will have to use built-in options for that, or create a custom plugin or chart type to render everything to your liking.
+Chart.js renders chart elements on an HTML5 canvas unlike several others, mostly D3.js-based, charting libraries that render as SVG. Canvas rendering makes Chart.js very performant, especially for large datasets and complex visualizations that would otherwise require thousands of SVG nodes in the DOM tree. At the same time, canvas rendering disallows CSS styling, so you will have to use built-in options for that, or create a custom plugin or chart type to render everything to your liking.
### Performance
-Chart.js is very well suited for large datasets. Such datasets can be efficiently ingested using the internal format so you can skip data [parsing](./general/performance.html#parsing) and [normalization](./general/performance.html#data-normalization). Alternatively, [data decimation](./configuration/decimation.html) can be configured to sample the dataset and reduce its size before rendering.
+Chart.js is very well suited for large datasets. Such datasets can be efficiently ingested using the internal format, so you can skip data [parsing](./general/performance.html#parsing) and [normalization](./general/performance.html#data-normalization). Alternatively, [data decimation](./configuration/decimation.html) can be configured to sample the dataset and reduce its size before rendering.
-In the end, the canvas rendering that Chart.js uses reduces the toll on your DOM tree in comparison to SVG rendering. Also, tree-shaking support allows you to include minimal parts of Chart.js code into your bundle, reducing bundle size and page load time.
+In the end, the canvas rendering that Chart.js uses reduces the toll on your DOM tree in comparison to SVG rendering. Also, tree-shaking support allows you to include minimal parts of Chart.js code in your bundle, reducing bundle size and page load time.
### Community
-Chart.js is [actively developed](https://github.com/chartjs/Chart.js/pulls?q=is%3Apr+is%3Aclosed) and maintained by the community. With minor [releases](https://github.com/chartjs/Chart.js/releases) on an approximately bi-monthly basis and major releases with breaking changes every couple of years, Chart.js keeps the balance between adding new features and making it a hassle to keep up with them.
+Chart.js is [actively developed](https://github.com/chartjs/Chart.js/pulls?q=is%3Apr+is%3Aclosed) and maintained by the community. With minor [releases](https://github.com/chartjs/Chart.js/releases) on an approximately bi-monthly basis and major releases with breaking changes every couple of years, Chart.js keeps the balance between adding new features and making it a hassle to keep up with them.
const data = dataset.data || (dataset.data = []);
const _data = this._data;
- // In order to correctly handle data addition/deletion animation (an thus simulate
+ // In order to correctly handle data addition/deletion animation (and thus simulate
// real-time charts), we need to monitor these data modifications and synchronize
- // the internal meta data accordingly.
+ // the internal metadata accordingly.
if (isObject(data)) {
this._data = convertObjectDataToArray(data);
projects / thirdparty / Chart.js.git / commitdiff
