2019-10-29 22:21:45 +01:00
# Chart.js 3.x Migration Guide
2020-02-08 00:03:33 +01:00
Chart.js 3.0 introduces a number of breaking changes. Chart.js 2.0 was released in April 2016. In the years since then, as Chart.js has grown in popularity and feature set, we've learned some lessons about how to better create a charting library. In order to improve performance, offer new features, and improve maintainability, it was necessary to break backwards compatibility, but we aimed to do so only when worth the benefit. Some major highlights of v3 include:
* Large [performance ](../general/performance.md ) improvements including the ability to skip data parsing and render charts in parallel via webworkers
* Additional configurability and scriptable options with better defaults
* Completely rewritten animation system
* Rewritten filler plugin with numerous bug fixes
* API Documentation generated and verified by TypeScript
2020-02-17 17:00:03 +01:00
* No more CSS injection
2020-02-08 00:03:33 +01:00
* Tons of bug fixes
2019-10-29 22:21:45 +01:00
2019-11-15 19:13:33 +01:00
## End user migration
2019-11-02 20:48:49 +01:00
2019-11-15 19:13:33 +01:00
### Setup and installation
2019-11-02 20:48:49 +01:00
2019-11-15 19:13:33 +01:00
* Chart.js is no longer providing the `Chart.bundle.js` and `Chart.bundle.min.js` . Please see the [installation ](installation.md ) and [integration ](integration.md ) docs for details on the recommended way to setup Chart.js if you were using these builds.
2020-02-28 01:40:31 +01:00
* `moment` is no longer specified as an npm dependency. If you are using the time scale, you must include one of [the available adapters ](https://github.com/chartjs/awesome#adapters ) and corresponding date library. You no longer need to exclude moment from your build.
2019-10-29 22:21:45 +01:00
### Options
2020-03-11 19:39:11 +01:00
A number of changes were made to the configuration options passed to the `Chart` constructor. Those changes are documented below.
* `hover.animationDuration` is now configured in `animation.active.duration`
* `responsiveAnimationDuration` is now configured in `animation.resize.duration`
* Polar area `startAngle` option is now consistent with `Radar` , 0 is at top and value is in degrees. Default is changed from `-½π` to `0` .
2019-11-22 00:46:49 +01:00
* `scales.[x/y]Axes` arrays were removed. Scales are now configured directly to `options.scales` object with the object key being the scale Id.
2019-10-29 22:21:45 +01:00
* `scales.[x/y]Axes.barPercentage` was moved to dataset option `barPercentage`
* `scales.[x/y]Axes.barThickness` was moved to dataset option `barThickness`
* `scales.[x/y]Axes.categoryPercentage` was moved to dataset option `categoryPercentage`
* `scales.[x/y]Axes.maxBarThickness` was moved to dataset option `maxBarThickness`
2019-12-28 14:19:32 +01:00
* `scales.[x/y]Axes.minBarLength` was moved to dataset option `minBarLength`
2019-11-22 00:46:49 +01:00
* `scales.[x/y]Axes.ticks.beginAtZero` was renamed to `scales[id].beginAtZero`
* `scales.[x/y]Axes.ticks.max` was renamed to `scales[id].max`
* `scales.[x/y]Axes.ticks.min` was renamed to `scales[id].min`
* `scales.[x/y]Axes.ticks.reverse` was renamed to `scales[id].reverse`
* `scales.[x/y]Axes.ticks.suggestedMax` was renamed to `scales[id].suggestedMax`
* `scales.[x/y]Axes.ticks.suggestedMin` was renamed to `scales[id].suggestedMin`
2020-02-04 01:22:09 +01:00
* `scales.[x/y]Axes.ticks.unitStepSize` was removed. Use `scales[id].ticks.stepSize`
2020-03-11 19:39:11 +01:00
* `scales.[x/y]Axes.ticks.userCallback` was renamed to `scales[id].ticks.callback`
2019-11-22 00:46:49 +01:00
* `scales.[x/y]Axes.time.format` was renamed to `scales[id].time.parser`
* `scales.[x/y]Axes.time.max` was renamed to `scales[id].max`
* `scales.[x/y]Axes.time.min` was renamed to `scales[id].min`
2020-03-11 19:39:11 +01:00
* `scales.[x/y]Axes.zeroLine*` options of axes were removed. Use scriptable scale options instead.
2020-02-20 00:13:40 +01:00
* The dataset option `steppedLine` was removed. Use `stepped`
2020-02-04 01:22:09 +01:00
* The dataset option `tension` was removed. Use `lineTension`
2020-03-11 19:39:11 +01:00
* Dataset options are now configured as `options[type].datasets` rather than `options.datasets[type]`
2020-01-26 21:33:20 +01:00
* To override the platform class used in a chart instance, pass `platform: PlatformClass` in the config object. Note that the class should be passed, not an instance of the class.
2019-10-29 22:21:45 +01:00
2020-03-11 19:39:11 +01:00
#### Defaults
* `global` namespace was removed from `defaults` . So `Chart.defaults.global` is now `Chart.defaults`
* `default` prefix was removed from defaults. For example `Chart.defaults.global.defaultColor` is now `Chart.defaults.color`
* `defaultColor` was renamed to `color`
* `defaultFontColor` was renamed to `fontColor`
* `defaultFontFamily` was renamed to `fontFamily`
* `defaultFontSize` was renamed to `fontSize`
* `defaultFontStyle` was renamed to `fontStyle`
* `defaultLineHeight` was renamed to `lineHeight`
#### Scales
The configuration options for scales is the largest change in v3. The `xAxes` and `yAxes` arrays were removed and axis options are individual scales now keyed by scale ID.
The v2 configuration below is shown with it's new v3 configuration
```javascript
options: {
scales: {
xAxes: [{
id: 'x',
type: 'time',
display: true,
scaleLabel: {
display: true,
labelString: 'Date'
},
ticks: {
major: {
enabled: true
},
fontStyle: function(context) {
return context.tick & & context.tick.major ? 'bold' : undefined;
},
fontColor: function(context) {
return context.tick & & context.tick.major ? '#FF0000' : undefined;
}
}
}],
yAxes: [{
id: 'y',
display: true,
scaleLabel: {
display: true,
labelString: 'value'
}
}]
}
}
```
And now, in v3:
```javascript
options: {
scales: {
x: {
type: 'time',
display: true,
scaleLabel: {
display: true,
labelString: 'Date'
},
ticks: {
major: {
enabled: true
},
fontStyle: function(context) {
return context.tick & & context.tick.major ? 'bold' : undefined;
},
fontColor: function(context) {
return context.tick & & context.tick.major ? '#FF0000' : undefined;
}
}
},
y: {
display: true,
scaleLabel: {
display: true,
labelString: 'value'
}
}
}
}
```
#### Animations
2019-12-27 23:13:24 +01:00
Animation system was completely rewritten in Chart.js v3. Each property can now be animated separately. Please see [animations ](../configuration/animations.md ) docs for details.
2020-03-11 19:39:11 +01:00
#### Customizability
* `custom` attribute of elements was removed. Please use scriptable options
* The `hover` property of scriptable options `context` object was renamed to `active` to align it with the datalabels plugin.
#### Interactions
* `interactions` are now limited to the chart area
* `{mode: 'label'}` was replaced with `{mode: 'index'}`
* `{mode: 'single'}` was replaced with `{mode: 'nearest', intersect: true}`
* `modes['X-axis']` was replaced with `{mode: 'index', intersect: false}`
* `options.onClick` is now limited to the chart area
#### Ticks
* `options.ticks.major` and `options.ticks.minor` were replaced with scriptable options for tick fonts.
* `Chart.Ticks.formatters.linear` and `Chart.Ticks.formatters.logarithmic` were replaced with `Chart.Ticks.formatters.numeric` .
#### Tooltip
* `xLabel` and `yLabel` were removed. Please use `index` and `value`
2019-12-27 23:13:24 +01:00
2019-10-29 22:21:45 +01:00
## Developer migration
### Removed
2020-03-11 19:39:11 +01:00
The following properties and methods were removed:
#### Chart
2020-02-18 00:45:30 +01:00
* `Chart.borderWidth`
2019-12-28 14:19:32 +01:00
* `Chart.chart.chart`
* `Chart.Controller`
2020-03-28 00:47:02 +01:00
* `Chart.innerRadius` now lives on doughnut, pie, and polarArea controllers
2020-02-18 00:45:30 +01:00
* `Chart.offsetX`
* `Chart.offsetY`
2020-03-28 00:47:02 +01:00
* `Chart.outerRadius` now lives on doughnut, pie, and polarArea controllers
2020-01-03 19:56:11 +01:00
* `Chart.prototype.generateLegend`
2020-02-17 17:00:03 +01:00
* `Chart.platform` . It only contained `disableCSSInjection` . CSS is never injected in v3.
2020-02-18 00:45:30 +01:00
* `Chart.radiusLength`
2019-12-28 14:19:32 +01:00
* `Chart.types`
2020-01-21 12:36:53 +01:00
* `Chart.Tooltip` is now provided by the tooltip plugin. The positioners can be accessed from `tooltipPlugin.positioners`
2020-03-11 19:39:11 +01:00
* `ILayoutItem.minSize`
#### Dataset Controller
2019-12-28 14:19:32 +01:00
* `DatasetController.addElementAndReset`
* `DatasetController.createMetaData`
* `DatasetController.createMetaDataset`
2020-03-11 19:39:11 +01:00
#### Elements
2019-12-28 14:19:32 +01:00
* `Element.getArea`
* `Element.height`
2020-03-01 15:07:39 +01:00
* `Element.hidden` was replaced by chart level status, usable with `getDataVisibility(index)` / `toggleDataVisibility(index)`
2019-12-28 14:19:32 +01:00
* `Element.initialize`
* `Element.inLabelRange`
2020-03-11 19:39:11 +01:00
* `Line.calculatePointY`
#### Helpers
2019-10-29 22:21:45 +01:00
* `helpers.addEvent`
* `helpers.aliasPixel`
* `helpers.configMerge`
2020-01-31 01:23:40 +01:00
* `helpers.findIndex`
* `helpers.findNextWhere`
* `helpers.findPreviousWhere`
2020-02-14 18:29:33 +01:00
* `helpers.extend` . Use `Object.assign` instead
2019-10-29 22:21:45 +01:00
* `helpers.indexOf`
2019-11-18 02:28:13 +01:00
* `helpers.lineTo`
2020-01-31 01:19:53 +01:00
* `helpers.longestText` was moved to the `helpers.canvas` namespace and made private
2019-10-31 23:45:13 +01:00
* `helpers.max`
2020-01-31 01:19:53 +01:00
* `helpers.measureText` was moved to the `helpers.canvas` namespace and made private
2019-12-28 14:19:32 +01:00
* `helpers.min`
2019-11-13 01:18:58 +01:00
* `helpers.nextItem`
2020-01-31 13:09:52 +01:00
* `helpers.niceNum`
2019-10-29 22:21:45 +01:00
* `helpers.numberOfLabelLines`
2019-11-13 01:18:58 +01:00
* `helpers.previousItem`
2019-10-29 22:21:45 +01:00
* `helpers.removeEvent`
2019-11-15 13:49:41 +01:00
* `helpers.roundedRect`
2019-10-29 22:21:45 +01:00
* `helpers.scaleMerge`
2019-12-25 14:21:42 +01:00
* `helpers.where`
2020-03-11 19:39:11 +01:00
#### Scales
2020-01-14 01:36:50 +01:00
* `LogarithmicScale.minNotZero`
2019-11-18 00:01:31 +01:00
* `Scale.getRightValue`
2020-01-05 22:42:15 +01:00
* `Scale.longestLabelWidth`
* `Scale.longestTextCache` is now private
2020-02-19 20:15:48 +01:00
* `Scale.margins` is now private
2019-11-18 00:01:31 +01:00
* `Scale.mergeTicksOptions`
* `Scale.ticksAsNumbers`
* `Scale.tickValues` is now private
2020-02-22 14:35:16 +01:00
* `TimeScale.getLabelCapacity` is now private
* `TimeScale.tickFormatFunction` is now private
2020-03-11 19:39:11 +01:00
#### Plugins (Legend, Title, and Tooltip)
* `IPlugin.afterScaleUpdate` . Use `afterLayout` instead
* `Legend.margins` is now private
2020-02-19 20:15:48 +01:00
* `Title.margins` is now private
2019-12-14 19:09:50 +01:00
* The tooltip item's `x` and `y` attributes were removed. Use `datasetIndex` and `index` to get the element and any corresponding data from it
2019-10-29 22:21:45 +01:00
2019-11-06 00:10:44 +01:00
#### Removal of private APIs
2020-03-11 19:39:11 +01:00
The following private APIs were removed.
2019-11-21 13:20:18 +01:00
* `Chart.data.datasets[datasetIndex]._meta`
2019-11-20 01:01:32 +01:00
* `Element._ctx`
2019-12-27 23:13:24 +01:00
* `Element._model`
* `Element._view`
2020-01-14 01:36:50 +01:00
* `LogarithmicScale._valueOffset`
2020-02-22 14:35:16 +01:00
* `TimeScale.getPixelForOffset`
2019-11-10 13:49:16 +01:00
* `TimeScale.getLabelWidth`
2020-01-12 00:10:32 +01:00
* `Tooltip._lastActive`
2019-11-06 00:10:44 +01:00
2019-10-29 22:21:45 +01:00
### Renamed
2020-03-11 19:39:11 +01:00
The following properties were renamed during v3 development:
2019-12-28 14:19:32 +01:00
* `Chart.Animation.animationObject` was renamed to `Chart.Animation`
* `Chart.Animation.chartInstance` was renamed to `Chart.Animation.chart`
* `helpers._decimalPlaces` was renamed to `helpers.math._decimalPlaces`
* `helpers.almostEquals` was renamed to `helpers.math.almostEquals`
* `helpers.almostWhole` was renamed to `helpers.math.almostWhole`
* `helpers.callCallback` was renamed to `helpers.callback`
2019-10-29 22:21:45 +01:00
* `helpers.clear` was renamed to `helpers.canvas.clear`
2019-12-28 14:19:32 +01:00
* `helpers.distanceBetweenPoints` was renamed to `helpers.math.distanceBetweenPoints`
2019-10-29 22:21:45 +01:00
* `helpers.drawRoundedRectangle` was renamed to `helpers.canvas.roundedRect`
2019-12-28 14:19:32 +01:00
* `helpers.getAngleFromPoint` was renamed to `helpers.math.getAngleFromPoint`
* `helpers.getMaximumHeight` was renamed to `helpers.dom.getMaximumHeight`
* `helpers.getMaximumWidth` was renamed to `helpers.dom.getMaximumWidth`
* `helpers.getRelativePosition` was renamed to `helpers.dom.getRelativePosition`
* `helpers.getStyle` was renamed to `helpers.dom.getStyle`
2019-10-29 22:21:45 +01:00
* `helpers.getValueAtIndexOrDefault` was renamed to `helpers.valueAtIndexOrDefault`
2019-12-28 14:19:32 +01:00
* `helpers.getValueOrDefault` was renamed to `helpers.valueOrDefault`
2019-10-29 22:21:45 +01:00
* `helpers.easingEffects` was renamed to `helpers.easing.effects`
* `helpers.log10` was renamed to `helpers.math.log10`
2019-12-17 14:04:40 +01:00
* `helpers.isNumber` was renamed to `helpers.math.isNumber`
* `helpers.sign` was renamed to `helpers.math.sign`
2019-12-28 14:19:32 +01:00
* `helpers.retinaScale` was renamed to `helpers.dom.retinaScale`
* `helpers.splineCurve` was renamed to `helpers.curve.splineCurve`
* `helpers.splineCurveMonotone` was renamed to `helpers.curve.splineCurveMonotone`
2019-12-17 14:04:40 +01:00
* `helpers.toDegrees` was renamed to `helpers.math.toDegrees`
* `helpers.toRadians` was renamed to `helpers.math.toRadians`
2019-12-14 19:22:57 +01:00
* `Scale.calculateTickRotation` was renamed to `Scale.calculateLabelRotation`
2019-12-27 23:13:24 +01:00
* `Tooltip.options.legendColorBackgroupd` was renamed to `Tooltip.options.multiKeyBackground`
2019-10-29 22:21:45 +01:00
2019-11-14 13:17:29 +01:00
#### Renamed private APIs
2020-03-11 19:39:11 +01:00
The private APIs listed below were renamed:
2020-02-10 23:57:22 +01:00
* `BarController.calculateBarIndexPixels` was renamed to `BarController._calculateBarIndexPixels`
* `BarController.calculateBarValuePixels` was renamed to `BarController._calculateBarValuePixels`
* `BarController.getStackCount` was renamed to `BarController._getStackCount`
* `BarController.getStackIndex` was renamed to `BarController._getStackIndex`
* `BarController.getRuler` was renamed to `BarController._getRuler`
* `Chart.destroyDatasetMeta` was renamed to `Chart._destroyDatasetMeta`
* `Chart.drawDataset` was renamed to `Chart._drawDataset`
* `Chart.drawDatasets` was renamed to `Chart._drawDatasets`
* `Chart.eventHandler` was renamed to `Chart._eventHandler`
* `Chart.handleEvent` was renamed to `Chart._handleEvent`
* `Chart.initialize` was renamed to `Chart._initialize`
* `Chart.resetElements` was renamed to `Chart._resetElements`
* `Chart.unbindEvents` was renamed to `Chart._unbindEvents`
* `Chart.updateDataset` was renamed to `Chart._updateDataset`
* `Chart.updateDatasets` was renamed to `Chart._updateDatasets`
* `Chart.updateLayout` was renamed to `Chart._updateLayout`
* `DatasetController.destroy` was renamed to `DatasetController._destroy`
* `DatasetController.insertElements` was renamed to `DatasetController._insertElements`
* `DatasetController.onDataPop` was renamed to `DatasetController._onDataPop`
* `DatasetController.onDataPush` was renamed to `DatasetController._onDataPush`
* `DatasetController.onDataShift` was renamed to `DatasetController._onDataShift`
* `DatasetController.onDataSplice` was renamed to `DatasetController._onDataSplice`
* `DatasetController.onDataUnshift` was renamed to `DatasetController._onDataUnshift`
* `DatasetController.removeElements` was renamed to `DatasetController._removeElements`
* `DatasetController.resyncElements` was renamed to `DatasetController._resyncElements`
2020-02-12 01:18:13 +01:00
* `RadialLinearScale.setReductions` was renamed to `RadialLinearScale._setReductions`
* `Scale.handleMargins` was renamed to `Scale._handleMargins`
2019-11-14 13:17:29 +01:00
* `helpers._alignPixel` was renamed to `helpers.canvas._alignPixel`
2019-12-27 23:13:24 +01:00
* `helpers._decimalPlaces` was renamed to `helpers.math._decimalPlaces`
2019-11-14 13:17:29 +01:00
2019-10-29 22:21:45 +01:00
### Changed
2020-03-11 19:39:11 +01:00
The APIs listed in this section have changed in signature or behaviour from version 2.
2019-11-05 00:07:01 +01:00
#### Scales
2019-11-19 13:09:50 +01:00
* `Scale.getLabelForIndex` was replaced by `scale.getLabelForValue`
* `Scale.getPixelForValue` now has only one parameter. For the `TimeScale` that parameter must be millis since the epoch
2020-02-28 01:38:10 +01:00
* `ScaleService.registerScaleType` was renamed to `ScaleService.registerScale` and now takes a scale constructors which is expected to have `id` and `defaults` properties.
2019-11-05 00:07:01 +01:00
##### Ticks
2019-10-31 23:45:13 +01:00
2019-11-19 13:09:50 +01:00
* `Scale.afterBuildTicks` now has no parameters like the other callbacks
2019-12-28 14:19:32 +01:00
* `Scale.buildTicks` is now expected to return tick objects
2019-11-19 13:09:50 +01:00
* `Scale.convertTicksToLabels` was renamed to `generateTickLabels` . It is now expected to set the label property on the ticks given as input
2019-12-28 14:19:32 +01:00
* `Scale.ticks` now contains objects instead of strings
* When the `autoSkip` option is enabled, `Scale.ticks` now contains only the non-skipped ticks instead of all ticks.
2019-10-31 23:45:13 +01:00
2019-11-05 00:07:01 +01:00
##### Time Scale
2019-10-29 22:21:45 +01:00
* `getValueForPixel` now returns milliseconds since the epoch
2019-11-10 13:52:12 +01:00
#### Controllers
##### Core Controller
* The first parameter to `updateHoverStyle` is now an array of objects containing the `element` , `datasetIndex` , and `index`
##### Dataset Controllers
2019-12-31 14:23:03 +01:00
* `updateElement` was replaced with `updateElements` now taking the elements to update, the `start` index, and `mode`
2019-12-14 19:09:50 +01:00
* `setHoverStyle` and `removeHoverStyle` now additionally take the `datasetIndex` and `index`
2019-11-10 13:52:12 +01:00
#### Interactions
* Interaction mode methods now return an array of objects containing the `element` , `datasetIndex` , and `index`
2020-01-05 16:42:42 +01:00
#### Layout
* `ILayoutItem.update` no longer has a return value
2020-01-15 23:13:36 +01:00
#### Helpers
##### Canvas Helper
* The second parameter to `drawPoint` is now the full options object, so `style` , `rotation` , and `radius` are no longer passed explicitly
2020-01-26 21:33:20 +01:00
#### Platform
2020-02-17 17:00:03 +01:00
* `Chart.platform` is no longer the platform object used by charts. Every chart instance now has a separate platform instance.
2020-01-26 21:33:20 +01:00
* `Chart.platforms` is an object that contains two usable platform classes, `BasicPlatform` and `DomPlatform` . It also contains `BasePlatform` , a class that all platforms must extend from.
* If the canvas passed in is an instance of `OffscreenCanvas` , the `BasicPlatform` is automatically used.