Array of arrays data format
When data is an array of arrays or tuples like [[10, 20], [15, null], [20, 10]], the first element is the index (x for vertical, y for horizontal charts) and the second element is the value (y by default).
charts/configuration
269 notes in this subject, read out of this brain and free to use. This is page 3 of 5.
Padding as single number value
If padding is specified as a single number value, it is applied to all four sides (left, top, right, bottom) of the chart.
Padding as object with directional properties
Padding can be specified as an object with properties: left, right, top, and bottom. Each property sets padding for that specific side. Omitted properties default to 0.
Padding {x, y} object shorthand
Padding can be specified as a shorthand object with x and y properties. The x property defines left and right padding to the same value, and the y property defines top and bottom padding to the same value.
Number padding example
This example shows how to set 20px padding on all sides using the number format: new Chart(ctx, { type: 'line', data: data, options: { layout: { padding: 20 } } });
Directional padding object example
This example shows how to set 50px padding only on the left side using the object format: new Chart(ctx, { type: 'line', data: data, options: { layout: { padding: { left: 50 } } } });
Dataset context properties
Dataset context object contains: active (true if an element is active/hovered), dataset (dataset at index datasetIndex), datasetIndex (index of the current dataset), index (same as datasetIndex), mode (the update mode), type (value: 'dataset'). It inherits from chart context.
Data context properties
Data context object contains: 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), element (the element such as point, arc, bar for this data), index (same as dataIndex), type (value: 'data'). It inherits from dataset context.
Tooltip context properties
Tooltip context object contains: tooltip (the tooltip object), tooltipItems (the items the tooltip is displaying), type (value: 'tooltip'). It inherits from chart context.
Indexable options accept arrays
Indexable options accept an array in which each item corresponds to the element at the same index. If there are fewer items than data, the items are looped over. In many cases, using a function is more appropriate if supported.
Option context hierarchy levels
There are multiple levels of context objects: chart, dataset (under chart), data (under dataset), scale (under chart), tick (under scale), pointLabel (under scale), and tooltip (under chart). Each level inherits its parent(s) and any contextual information stored in the parent is available through the child.
Option resolution order for dataset level
Dataset level options are resolved in this order: dataset, options.datasets[dataset.type], options, overrides[config.type].datasets[dataset.type], defaults.datasets[dataset.type], defaults. The dataset.type defaults to config.type if not specified.
Scriptable options accept functions
Scriptable options accept a function which is called for each of the underlying data values. The function takes a context argument representing contextual information. A resolver is passed as a second parameter that can be used to access other options in the same context. The context argument should be validated in the scriptable function because the function can be invoked in different contexts.
Chart context properties
Chart context object contains: chart (the associated chart), type (value: 'chart').
Option resolution order for chart level
Chart level options are resolved in this order: options, overrides[config.type], defaults.
Scriptable option example with context and resolver
Example of scriptable options that use context and resolver: color: function(context) { const index = context.dataIndex; const value = context.dataset.data[index]; return value < 0 ? 'red' : index % 2 ? 'blue' : 'green'; }, borderColor: function(context, options) { const color = options.color; return Chart.helpers.color(color).lighten(0.2); }
Indexable option example
Example of indexable option: color: ['red', 'blue', 'green', 'black']. The first element applies to data at index 0, second to index 1, third to index 2, fourth to index 3, and so on.
Chart.js CDN URL
Chart.js can be included from CDN using the URL https://cdn.jsdelivr.net/npm/chart.js
Chart.js installation methods
Chart.js can be installed from npm or a CDN, and can be integrated with bundlers, loaders, and front-end frameworks. It can also be used from Node.js.
Canvas element setup for charts
Charts should be placed in their own container div with a canvas element for proper responsiveness. The canvas element should have an id attribute to reference it when instantiating the Chart.
Chart.js rendering in web workers
Chart.js supports rendering in web workers via OffscreenCanvas API. Pass an OffscreenCanvas to the Chart constructor instead of a Canvas element. This moves Chart.js calculations to a separate thread, freeing the main thread for other tasks. Web workers can make HTTP requests, allowing config and data generation on the worker side.
Disable parsing for prepared data
To improve performance with prepared data, provide data in the internal format accepted by the dataset and scales, then set `parsing: false` to skip parsing overhead.
Use normalized: true option for sorted data
Chart.js renders fastest when data has indices that are unique, sorted, and consistent across datasets. Set `normalized: true` to inform Chart.js that data is already prepared this way. Even without this option, providing sorted data can improve performance.
Web worker data transfer tips
When using Chart.js in web workers, minimize config and data object sizes to reduce transfer overhead between threads. Pass data as ArrayBuffers which transfer quickly. Functions cannot be transferred between threads, so strip them from config before transferring and add them back later. Resizing the chart must be done manually since OffscreenCanvas lacks event listeners.
Web worker limitations
Chart.js plugins that use the DOM will not work in web workers, including any mouse interactions. Ensure fallback support for older browsers that do not support OffscreenCanvas.
Web worker main thread code example
const config = {}; const canvas = new HTMLCanvasElement(); const offscreenCanvas = canvas.transferControlToOffscreen(); const worker = new Worker('worker.js'); worker.postMessage({canvas: offscreenCanvas, config}, [offscreenCanvas]);
Web worker Chart.js code example
onmessage = function(event) { const {canvas, config} = event.data; const chart = new Chart(canvas, config); // Resizing the chart must be done manually, since OffscreenCanvas does not include event listeners. canvas.width = 100; canvas.height = 100; chart.resize(); };
Babel loose mode for better performance
When transpiling with Babel, use `loose` mode for better performance. Babel 7.9 changed how classes are constructed, and without loose mode it is slow.
Building Chart.js from GitHub repository
If you download or clone the Chart.js repository from GitHub, you must build Chart.js to generate the dist files. Chart.js no longer comes with prebuilt release versions, so downloading the repository is not strongly advised as an installation method compared to using npm or CDN alternatives.
Install Chart.js via npm
Chart.js can be installed using npm with the command: npm install chart.js
Chart.js available on jsDelivr
Chart.js built files are available through jsDelivr at https://www.jsdelivr.com/package/npm/chart.js?path=dist
Chart.js available on CDNJS
Chart.js built files are available on CDNJS at https://cdnjs.com/libraries/Chart.js
Download Chart.js from GitHub
The latest version of Chart.js can be downloaded from https://github.com/chartjs/Chart.js/releases/latest
Tree-shaking benefits
Using individual component imports instead of chart.js/auto can reduce bundle size by approximately 25% or more, as demonstrated by going from 265 KB to 208 KB when removing unused Chart.js code.
Multiple datasets with different data filters
Chart.js plots each dataset independently and allows custom styles per dataset. Multiple datasets can be used to segment data and apply different colors or styles to each segment. Datasets can be toggled on and off independently.
Chart aspect ratio configuration
Chart.js supports an aspectRatio option that controls the ratio of width to height. By default, radial charts (e.g., doughnut) have an aspect ratio of 1, and other charts have an aspect ratio of 2.
Missing controller error message
If a chart controller is not registered, Chart.js will throw an error in the browser console with a message like 'Error: "[type]" is not a registered controller' where [type] is the chart type name.
Chart data structure
Chart.js charts require a data object containing labels (often numeric or textual descriptions of data points) and an array of datasets. Each dataset requires a label and contains an array of data points.
Chart.js imports from chart.js/auto
The special import path 'chart.js/auto' loads all available Chart.js components which is convenient for prototyping but disallows tree-shaking. To enable tree-shaking in production, replace 'chart.js/auto' with individual component imports.
Canvas element required for Chart.js
Chart.js requires a canvas tag with an id attribute to reference the chart. Chart.js charts are responsive by default and take the whole enclosing container, so set the container width to control chart width.
Pie chart minimum components
Pie chart requires PieController and ArcElement. It does not use scales.
Chart.js is tree-shakeable
Chart.js is tree-shakeable, requiring you to import and register only the controllers, elements, scales, and plugins you plan to use when optimizing bundle size.
getRelativePosition helper example
The example shows using getRelativePosition helper to convert click events to data values: import Chart from 'chart.js/auto'; import { getRelativePosition } from 'chart.js/helpers'; const chart = new Chart(ctx, { type: 'line', data: data, options: { onClick: (e) => { const canvasPosition = getRelativePosition(e, chart); const dataX = chart.scales.x.getValueForPixel(canvasPosition.x); const dataY = chart.scales.y.getValueForPixel(canvasPosition.y); } } });
Script tag integration
Chart.js can be loaded via script tag with the UMD build at path/to/chartjs/dist/chart.umd.min.js. After loading, create a chart instance with new Chart(ctx, {...}).
RequireJS integration example
RequireJS example: require(['path/to/chartjs/dist/chart.umd.min.js'], function(Chart){ const myChart = new Chart(ctx, {...}); });
RequireJS with UMD build
RequireJS can only load AMD modules, so use one of the UMD builds (dist/chart.umd.min.js) instead.
CommonJS dynamic import
Because Chart.js is an ESM library, in CommonJS modules use dynamic import: const { Chart } = await import('chart.js');
ESM auto import for bundlers
For bundlers like Webpack or Rollup, importing from 'chart.js/auto' ensures all features are available but results in a larger bundle size.
Helper functions import for bundlers
Helper functions like getRelativePosition must be imported separately from 'chart.js/helpers' and used as stand-alone functions when using bundlers.
Example: Node.js Chart.js with skia-canvas
This example shows how to generate a line chart in Node.js using Chart.js and skia-canvas: import {CategoryScale, Chart, LinearScale, LineController, LineElement, PointElement} from 'chart.js'; import {Canvas} from 'skia-canvas'; import fsp from 'node:fs/promises'; Chart.register([ CategoryScale, LineController, LineElement, LinearScale, PointElement ]); const canvas = new Canvas(400, 300); const chart = new Chart( canvas, // TypeScript needs "as any" here { type: 'line', data: { labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'], datasets: [{ label: '# of Votes', data: [12, 19, 3, 5, 2, 3], borderColor: 'red' }] } } ); const pngBuffer = await canvas.toBuffer('png', {matte: 'white'}); await fsp.writeFile('output.png', pngBuffer); chart.destroy();
Node.js server-side chart generation with Chart.js
Chart.js can be used in Node.js for server-side generation of plots with help from NPM packages such as node-canvas or skia-canvas.
Chart.js TypeScript support
Chart.js comes with built-in TypeScript typings.
Chart.js release cycle
Chart.js has minor releases on an approximately bi-monthly basis and major releases with breaking changes every couple of years.
Chart.js performance with large datasets
Chart.js is well-suited for large datasets. Data can be efficiently ingested using the internal format to skip parsing and normalization. Data decimation can be configured to sample and reduce dataset size before rendering.
Chart.js framework integrations
Chart.js is compatible with popular JavaScript frameworks including React, Vue, Svelte, and Angular. Well-maintained wrapper packages are available for native integration with these frameworks.
Chart.js canvas rendering
Chart.js renders chart elements on an HTML5 canvas rather than SVG. Canvas rendering makes Chart.js very performant, especially for large datasets and complex visualizations. However, canvas rendering disallows CSS styling, so built-in options or custom plugins must be used for styling.
Chart.js built-in chart types
Chart.js provides a set of frequently used built-in chart types and also supports combining multiple chart types into a mixed chart on the same canvas.
Chart.js creation and licensing
Chart.js was created and announced in 2013. It is open-source and licensed under the MIT license.
Chart.js popularity and adoption
Chart.js is the most popular charting library for JavaScript according to GitHub stars (~60,000) and npm downloads (~2,400,000 weekly).
Tooltip styling is now consistent across chart types
In Chart.js 4.0, charts no longer override the default tooltip callbacks, so all chart types have the same-looking tooltips.