Chart.js/docs/getting-started/v3-migration.md

Chart.js 3.x Migration Guide

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 necessary.

End user migration

Setup and installation

• Chart.js is no longer providing the Chart.bundle.js and Chart.bundle.min.js. Please see the installation and integration docs for details on the recommended way to setup Chart.js if you were using these builds.
• moment is no longer specified as an npm dependency. If you are using the time scale, you must include one of the available adapters and corresponding date library. If you are using a date library other than moment, you no longer need to exclude moment from your build.

Ticks

• options.ticks.userCallback was renamed to options.ticks.callback

Tooltip

• xLabel and yLabel were removed. Please use index and value

Interactions

• options.onClick is now limited to the chart area
• {mode: 'single'} was replaced with {mode: 'nearest', intersect: true}
• {mode: 'label'} was replaced with {mode: 'index'}
• modes['X-axis'] was replaced with {mode: 'index', intersect: false}

Customizability

• custom attribute of elements was removed. Please use scriptable options
• The zeroLine* options of axes were removed. Use scriptable scale options instead.
• The hover property of scriptable options context object was renamed to active to align it with the datalabels plugin.

Options

• The dataset option tension was renamed to lineTension
• 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.minBarLength was moved to dataset option minBarLength
• scales.[x/y]Axes.maxBarThickness was moved to dataset option maxBarThickness
• scales.[x/y]Axes.ticks.beginAtZero was renamed to scales.[x/y]Axes.beginAtZero
• scales.[x/y]Axes.ticks.max was renamed to scales.[x/y]Axes.max
• scales.[x/y]Axes.ticks.min was renamed to scales.[x/y]Axes.min
• scales.[x/y]Axes.ticks.reverse was renamed to scales.[x/y]Axes.reverse
• scales.[x/y]Axes.ticks.suggestedMax was renamed to scales.[x/y]Axes.suggestedMax
• scales.[x/y]Axes.ticks.suggestedMin was renamed to scales.[x/y]Axes.suggestedMin
• scales.[x/y]Axes.time.format was renamed to scales.[x/y]Axes.time.parser
• scales.[x/y]Axes.time.max was renamed to scales.[x/y]Axes.max
• scales.[x/y]Axes.time.min was renamed to scales.[x/y]Axes.min

Developer migration

Removed

• helpers.addEvent
• helpers.aliasPixel
• helpers.configMerge
• helpers.indexOf
• helpers.lineTo
• helpers.min
• helpers.max
• helpers.nextItem
• helpers.numberOfLabelLines
• helpers.previousItem
• helpers.removeEvent
• helpers.roundedRect
• helpers.scaleMerge
• Chart.Controller
• Chart.chart.chart
• Chart.types
• DatasetController.addElementAndReset
• Element.getArea
• Element.height
• Element.inLabelRange
• IPlugin.afterScaleUpdate. Use afterLayout instead
• Line.calculatePointY
• Scale.getRightValue
• Scale.mergeTicksOptions
• Scale.ticksAsNumbers
• Scale.handleDirectionalChanges is now private
• Scale.tickValues is now private

Removal of private APIs

• Element._ctx
• Element._model.datasetLabel
• Element._model.label
• Point._model.tension
• Point._model.steppedLine
• TimeScale._getPixelForOffset
• TimeScale.getLabelWidth

Renamed

• helpers.clear was renamed to helpers.canvas.clear
• helpers.drawRoundedRectangle was renamed to helpers.canvas.roundedRect
• helpers.callCallback was renamed to helpers.callback
• helpers.getValueOrDefault was renamed to helpers.valueOrDefault
• helpers.getValueAtIndexOrDefault was renamed to helpers.valueAtIndexOrDefault
• helpers.easingEffects was renamed to helpers.easing.effects
• helpers.log10 was renamed to helpers.math.log10
• Chart.Animation.animationObject was renamed to Chart.Animation
• Chart.Animation.chartInstance was renamed to Chart.Animation.chart
• DatasetController.createMetaData and DatasetController.createMetaDataset were replaced with DatasetController.createElement
• DatasetController.updateElement was renamed to DatasetController.updateElements
• TimeScale.getLabelCapacity was renamed to TimeScale._getLabelCapacity
• TimeScale.tickFormatFunction was renamed to TimeScale._tickFormatFunction
• TimeScale.getPixelForOffset was renamed to TimeScale._getPixelForOffset

Renamed private APIs

• helpers._alignPixel was renamed to helpers.canvas._alignPixel

Changed

Scales

• 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

Ticks

• When the autoSkip option is enabled, Scale.ticks now contains only the non-skipped ticks instead of all ticks.
• Scale.ticks now contains objects instead of strings
• Scale.buildTicks is now expected to return tick objects
• Scale.afterBuildTicks now has no parameters like the other callbacks
• Scale.convertTicksToLabels was renamed to generateTickLabels. It is now expected to set the label property on the ticks given as input

Time Scale

• getValueForPixel now returns milliseconds since the epoch

Controllers

Core Controller

• The first parameter to updateHoverStyle is now an array of objects containing the element, datasetIndex, and index

Dataset Controllers

• setHoverStyle now additionally takes the datasetIndex and index

Interactions

• Interaction mode methods now return an array of objects containing the element, datasetIndex, and index