ChartMeta type parameter order changed
In Chart.js 4.0, the order of the ChartMeta type parameters has been changed from <Element, DatasetElement, Type> to <Type, Element, DatasetElement>.
charts/configuration
269 notes in this subject, read out of this brain and free to use. This is page 4 of 5.
Chart.js 4.0 is ESM-only
Chart.js 4.0 is an ESM-only package, though the UMD bundle is still available. To use Chart.js 4.0, your project should also be an ES module. Ensure your package.json includes "type": "module". For Jest compatibility issues, consult Jest's ESM documentation or consider migrating to Vitest, which has ESM support out of the box.
Chart.js 4.0 breaking changes overview
Chart.js 4.0 introduces breaking changes that require migration. The library aims to minimize breaking changes, making them only when the benefit justifies compatibility loss.
Distribution bundle files renamed in Chart.js 4.0
In Chart.js 4.0, dist/chart.js has been removed. dist/chart.min.js has been renamed to dist/chart.umd.min.js (and before version 4.5.0 it was dist/chart.umd.js). dist/chart.esm.js has been renamed to dist/chart.js.
maintainAspectRatio now respects container height
In Chart.js 4.0, the maintainAspectRatio option now respects container height.
Tooltip callbacks returning undefined use default behavior
In Chart.js 4.0, if a tooltip callback returns undefined, the default callback will be used.
Creating a derived chart type example
A derived chart type can be created by defining a custom chart type (e.g., 'derivedBubble') that extends an existing chart. The example shows creating a derived bubble chart with custom dataset properties like boxStrokeStyle. The configuration specifies the type as the custom name, and uses standard data and options structures including responsive true and plugins configuration.
Derived chart type uses custom type name
When creating a derived chart type, you set the config type property to your custom name (e.g., 'derivedBubble') rather than using a built-in chart type name.
Accessing chart area coordinates for tooltip positioning
The chart.chartArea object contains left, right, top, and bottom properties that define the rectangular bounds of the chart drawing area. These can be used to calculate tooltip positions, such as centering with (left + right) / 2 for x-coordinate and (top + bottom) / 2 for y-coordinate.
Chart.getActiveElements() method
Chart.getActiveElements() returns an array of currently active elements. It can be used to check if any elements are currently active before setting new active elements.
Chart.update() triggers re-render after programmatic changes
After calling setActiveElements() on either the chart or tooltip, chart.update() must be called to trigger a re-render and display the changes.
Chart.setActiveElements() method signature
Chart.setActiveElements() takes an array of objects with datasetIndex and index properties to programmatically activate chart elements. Each object in the array represents a data element identified by its dataset index and data point index within that dataset.
Programmatic hover trigger example
function triggerHover(chart) { if (chart.getActiveElements().length > 0) { chart.setActiveElements([]); } else { chart.setActiveElements([ { datasetIndex: 0, index: 0, }, { datasetIndex: 1, index: 0, } ]); } chart.update(); } This example shows how to toggle hover state on specific data points across multiple datasets by setting active elements and updating the chart.
Interaction mode 'nearest' with axis 'x'
The interaction mode 'nearest' with axis 'x' means the chart will trigger interactions for the nearest data point on the x-axis. When intersect is false, the interaction triggers even if the cursor is not directly over a data point, as long as it is over the x-axis at that data point's position.
Chart area coordinates
The chart area can be accessed via context.chart.chartArea, which provides properties: left, right, top, and bottom. These define the boundaries of the drawable chart area within the canvas.
Scriptable options in Chart.js
Options like animation.delay can be scriptable, meaning they accept either a static value or a function that receives a context object and returns a value dynamically based on that context.
Chart.update() method refreshes chart with new data
Calling chart.update() causes the chart to re-render with the current data. This is used after modifying chart.data.datasets, chart.data.labels, or individual dataset properties to display the changes.
Interaction mode nearest with axis option
The interaction configuration can specify mode: 'nearest' with axis: 'x' to detect interactions based on the nearest point along the x-axis. Additional properties include intersect: false to also detect points that do not directly intersect the cursor.
Getting dataset metadata and context for individual data points
Use chart.getDatasetMeta(datasetIndex) to retrieve metadata for a dataset. The metadata object has a controller with a getContext(index) method that returns context information for a specific data point in that dataset.
Line chart interaction intersect option
The interaction.intersect option set to false allows interaction events to trigger even when the mouse cursor is not directly on a data point, useful for line charts.
Interaction intersect option for tooltips
The interaction.intersect property can be set to false to show tooltips even when the cursor is not directly over a data point.
Chart.update() after modifying scale options
After changing chart.options.scales.y.stacked, call chart.update() to refresh the chart with the new configuration.
Sample data is autogenerated
The data used in Chart.js samples is autogenerated using custom functions. These functions do not ship with the library. For more information about the data generation utilities, see the utils page.
Samples are not production-ready
The samples in the documentation are made for demonstration purposes only and will not work out of the box if copied and pasted into your own website because of how the documentation is built. Some boilerplate code is hidden. For a production-ready sample, refer to the usage page in the getting-started documentation.
Running samples locally
To run Chart.js samples locally, clone the Chart.js repository from GitHub, run `pnpm ci` to install all packages, then run `pnpm run docs:dev` to build the documentation. After the build completes, the samples are available at localhost:8080/samples/.
Actions block in samples
Samples contain an `actions` code block that is not part of Chart.js itself. These actions are internally transformed by a documentation plugin into separate buttons with `onClick` listeners. To implement similar functionality, create buttons and add `onClick` event listeners that call the chart variable and execute the desired logic.
Interaction mode index for multi-axis charts
For multi-axis line charts, setting interaction.mode to 'index' with intersect set to false allows tooltips and interactions to work across all datasets regardless of which axis they use, showing data from all datasets at the same label position.
Chart.js show() method for datasets
The chart.show(datasetIndex) method shows a hidden dataset by index. Multiple dataset indices can be passed as separate arguments, e.g., chart.show(0, 1) shows datasets at indices 0 and 1.
Doughnut chart update() method
The chart.update() method refreshes the chart after data modifications such as changing dataset values, adding datasets, adding labels, or removing datasets and data.
Chart.js hide() method for datasets
The chart.hide(datasetIndex) method hides a dataset by index. Multiple dataset indices can be passed as separate arguments, e.g., chart.hide(0, 1) hides datasets at indices 0 and 1.
chart.isDatasetVisible() method checks dataset visibility
The chart.isDatasetVisible(datasetIndex) method returns a boolean indicating whether a dataset is currently visible, accounting for the dataset's hidden state in its metadata.
Stack property groups datasets for stacking
The `stack` property on a dataset groups datasets together for stacking purposes. Multiple datasets with the same `stack` value will have their values stacked together on the same axis. Datasets with different `stack` values will be stacked separately.
Scriptable options receive context with parsed data
Scriptable options in Chart.js receive a context object (ctx) that contains parsed data. For bar charts, ctx.parsed.y contains the parsed y-value of the bar being rendered.
Dataset controller defaults moved to overrides in v3
In Chart.js 3.x, dataset controller defaults were relocated to `overrides`. For example, `Chart.defaults.line` is now `Chart.overrides.line`.
default prefix removed from defaults in v3
In Chart.js 3.x, the `default` prefix was removed from defaults. For example, `Chart.defaults.global.defaultColor` is now `Chart.defaults.color`.
defaultColor split into three properties in v3
In Chart.js 3.x, `defaultColor` was split into `color`, `borderColor`, and `backgroundColor`.
defaultFontColor renamed to color in v3
In Chart.js 3.x, `defaultFontColor` was renamed to `color`.
defaultFontFamily renamed to font.family in v3
In Chart.js 3.x, `defaultFontFamily` was renamed to `font.family`.
defaultFontSize renamed to font.size in v3
In Chart.js 3.x, `defaultFontSize` was renamed to `font.size`.
defaultFontStyle renamed to font.style in v3
In Chart.js 3.x, `defaultFontStyle` was renamed to `font.style`.
defaultLineHeight renamed to font.lineHeight in v3
In Chart.js 3.x, `defaultLineHeight` was renamed to `font.lineHeight`.
custom attribute removed, use scriptable options in v3
In Chart.js 3.x, the `custom` attribute of elements was removed. Use scriptable options instead.
hover renamed to active in scriptable options context in v3
In Chart.js 3.x, the `hover` property of scriptable options `context` object was renamed to `active` to align it with the datalabels plugin.
Root interaction options scope added in v3
In Chart.js 3.x, a root options scope for common interaction options was added. `options.hover` and `options.plugins.tooltip` now both extend from `options.interaction`. Defaults are defined at `defaults.interaction` level.
Interactions limited to chart area in v3
In Chart.js 3.x, interactions are limited to the chart area plus allowed overflow.
Interaction mode label replaced with index in v3
In Chart.js 3.x, `{mode: 'label'}` was replaced with `{mode: 'index'}`.
Interaction mode single replaced in v3
In Chart.js 3.x, `{mode: 'single'}` was replaced with `{mode: 'nearest', intersect: true}`.
X-axis interaction mode replaced in v3
In Chart.js 3.x, `modes['X-axis']` was replaced with `{mode: 'index', intersect: false}`.
onClick limited to chart area in v3
In Chart.js 3.x, `options.onClick` is now limited to the chart area.
onClick and onHover receive chart instance in v3
In Chart.js 3.x, `options.onClick` and `options.onHover` now receive the chart instance as a 3rd argument.
onHover event wrapping in v3
In Chart.js 3.x, `options.onHover` now receives a wrapped `event` as the first parameter. The previous first parameter value is accessible via `event.native`.
hover.onHover removed in v3
In Chart.js 3.x, `options.hover.onHover` was removed. Use `options.onHover` instead.
updateElement changed to updateElements in v3
In Chart.js 3.x, when building elements in a controller, call `updateElements` to provide element properties. Methods such as `getSharedOptions` and `includeOptions` have been added to skip redundant computation.
Chart.js 3.0 distributed files are lowercase
In Chart.js 3.x, distributed files are now in lower case. For example, the main file is named `dist/chart.js` instead of previous naming conventions.
Chart.bundle.js removed in v3
Chart.js 3.x no longer provides the `Chart.bundle.js` and `Chart.bundle.min.js` files. Users should refer to the installation and integration documentation for the recommended setup approach.
Canvas reuse error in v3
The Chart constructor in Chart.js 3.x will throw an error if the canvas/context provided is already in use by another chart instance.
Tree-shaking support in v3
Chart.js 3.x is tree-shakeable. When using it as an npm module and wanting to utilize tree-shaking benefits, you must import and register the controllers, elements, scales and plugins you need. Importing via a script tag or from the `auto` register path will not provide tree-shaking benefits. You must call `Chart.register()` with the desired components.
v3 registration example
Example of registering components in Chart.js 3 for tree-shaking: import { Chart, LineController, LineElement, PointElement, LinearScale, Title } from `chart.js` Chart.register(LineController, LineElement, PointElement, LinearScale, Title); const chart = new Chart(ctx, { type: 'line', options: { plugins: { title: { display: true, text: 'Chart Title' } }, scales: { x: { type: 'linear' }, y: { type: 'linear' } } } })
Indexable options now loop in v3
In Chart.js 3.x, indexable options loop through the provided values. For example, `backgroundColor: ['red', 'green']` will result in alternating 'red' and 'green' colors if there are more than 2 data points.
Options resolved via proxies in v3
Most options in Chart.js 3.x are resolved utilizing proxies instead of merging with defaults. This enables different resolution routes for different contexts and allows using other resolved options in scriptable options. Options are by default scriptable and indexable unless disabled.