.getSortedVisibleDatasetMetas() method
getSortedVisibleDatasetMetas() returns an array of all the dataset meta's in the order that they are drawn on the canvas that are not hidden.
charts/configuration
269 notes in this subject, read out of this brain and free to use. This is page 2 of 5.
.resize(width?, height?) method
resize(width?, height?) manually resizes the canvas element. This is run each time the canvas container is resized, but can be called manually if the size of the canvas node's container element changes. Call .resize() with no parameters to have the chart take the size of its container element, or pass explicit dimensions. Returns 'this' for chainability.
.getDatasetMeta(index) method
getDatasetMeta(index) looks for the dataset that matches the given index and returns that metadata. This returned data has all of the metadata that is used to construct the chart. The data property of the metadata contains information about each point, bar, etc. depending on the chart type.
Built-in controller types in Chart.js
The built-in controller types are: BarController, BubbleController, DoughnutController, LineController, PieController, PolarAreaController, RadarController, and ScatterController. These are available in the UMD package directly under Chart, for example Chart.BarController.
Extend an existing chart type example
Example showing how to extend the BubbleController to create a custom chart type that draws a red box around the first point: import {BubbleController} from 'chart.js'; class Custom extends BubbleController { draw() { super.draw(arguments); const meta = this.getMeta(); const pt0 = meta.data[0]; const {x, y} = pt0.getProps(['x', 'y']); const {radius} = pt0.options; const ctx = this.chart.ctx; ctx.save(); ctx.strokeStyle = 'red'; ctx.lineWidth = 1; ctx.strokeRect(x - radius, y - radius, 2 * radius, 2 * radius); ctx.restore(); } }; Custom.id = 'derivedBubble'; Custom.defaults = BubbleController.defaults; Chart.register(Custom); new Chart(ctx, { type: 'derivedBubble', data: data, options: options });
Dataset controller optional methods
Dataset controllers may optionally override: draw() to render the dataset representation, initialize() to set up the controller, linkScales() to link the dataset to a scale (not used in polar area and doughnut controllers), and parse(start, count) to parse data into controller metadata.
TypeScript typings for new chart types using declaration merging
To provide TypeScript typings for a new chart type, create a .d.ts file that augments the ChartTypeRegistry interface using declaration merging. Example for a chart extending bubble: import { ChartTypeRegistry } from 'chart.js'; declare module 'chart.js' { interface ChartTypeRegistry { derivedBubble: ChartTypeRegistry['bubble'] } }
Create a new chart type by extending Chart.DatasetController
To create a new chart type, define a class that extends Chart.DatasetController, then register it with Chart.register(). The new chart type can then be instantiated by passing its registered type name to the Chart constructor.
Dataset controller interface - defaults property
A dataset controller must define a defaults object with two properties: datasetElementType (string | null | false) which specifies the element type to create for the dataset, and dataElementType (string | null | false) which specifies the element type to create for each data value. If set to false or null, no element is created.
Dataset controller interface - required properties and methods
A dataset controller must implement: id (string) - the controller identifier, and update(mode) - a method that updates elements in response to new data. The mode parameter can be 'active', 'hide', 'reset', 'resize', 'show', or undefined.
Migration from Chart.js v2 to v3
Version 3 has a largely different API than earlier versions. Most earlier version options have current equivalents or are the same. Migration guidance is available in the v3 migration guide. Documentation for v2.9.4 is available at https://www.chartjs.org/docs/2.9.4/ and v1.x documentation is available at https://github.com/chartjs/Chart.js/tree/v1.1.1/docs.
Latest Chart.js documentation and samples
The latest documentation and samples, including unreleased features, are available at https://www.chartjs.org/docs/master/ and https://www.chartjs.org/samples/master/.
Browser support in Chart.js version 3+
Chart.js version 3 and later support all modern and up-to-date browsers including Chrome, Edge, Firefox, and Safari. Internet Explorer 11 support was dropped as of version 3. Browser support for the canvas element is available in all modern and major mobile browsers.
Development builds available for testing
Latest development builds are available at https://www.chartjs.org/dist/master/chart.js and https://www.chartjs.org/dist/master/chart.umd.min.js. Development builds must not be used for production purposes or as replacement for a CDN.
Image-based test requirements in Chart.js
Generated charts in image-based tests should be as minimal as possible and focus only on the tested feature to prevent failure if another feature breaks. For example, disable the title and legend when testing scales. It is recommended to hide all scales in image-based tests and to disable animations to improve cross-browser test stability.
Creating an image-based test in Chart.js
To create a new image-based test: (1) Create a JS or JSON file defining chart config and generation options. (2) Add this file in `test/fixtures/{spec.name}/{feature-name}.json`. (3) Add a describe line to the beginning of `test/specs/{spec.name}.tests.js` if it doesn't exist yet. (4) Run `pnpm run dev`. (5) Click the Debug button (top/right) and verify the test fails with the associated canvas visible. (6) Right-click on the chart and Save image as `test/fixtures/{spec.name}/{feature-name}.png` without activating the tooltip or hover functionality. (7) Refresh the browser page to verify the test passes. (8) Verify test relevancy by changing feature values slightly in the JSON file. Tests should pass in both browsers.
Chart.js contribution guidelines for PRs
Before opening a PR for major additions or changes, discuss the expected API and/or implementation by filing an issue or asking in the Chart.js Discord #dev channel. Consider whether changes are useful for all users or if a plugin would be more appropriate. Code must pass tests and eslint standards via `pnpm test`. Add unit tests and documentation for new functionality in the `test/` and `docs/` directories. Avoid breaking changes unless there is an upcoming major release. Prefer new methods as private whenever possible, either as top-level functions outside a class or prefixed with `_` with `@private` JSDoc if inside a class, as public APIs are difficult to change later without breaking backward compatibility.
Documentation server for Chart.js docs
Chart.js uses Vuepress to manage docs contained as Markdown files in the docs directory. The doc server can be run locally using the command `pnpm run docs:dev`.
Adjusting image-based test tolerances in Chart.js
When an image-based test fails, the expected and actual images are shown. If tests do not pass after setup, adjust `tolerance` and/or `threshold` at the beginning of the JSON file, keeping them as low as possible. To see images even when tests pass, set `"debug": true` in the JSON file.
Available Chart.js development commands
The following commands are available from the repository root: `pnpm run build` builds dist files in ./dist; `pnpm run autobuild` builds and watches for source changes; `pnpm run dev` runs tests and watches for source and test changes; `pnpm run lint` performs code linting with ESLint and tsc; `pnpm test` performs code linting and runs unit tests with coverage. Both `pnpm run dev` and `pnpm test` can be appended with a string to match spec filenames, for example `pnpm run dev plugins` will start karma in watch mode for `test/specs/**/*plugin*.js`.
Prerequisites for local Chart.js development
Node and pnpm must be installed. After cloning the Chart.js repository to a local directory and navigating to it in the command line, run `pnpm install` to install local development dependencies.
Update options by mutating in place
Mutating the options property in place preserves other option properties, including those calculated by Chart.js. Call chart.update() after making changes. Example: chart.options.plugins.title.text = 'new title'; chart.update();
Update options as new object
Creating a new options object discards old options and is like creating a new chart with the options. Assign the new object to chart.options and call chart.update(). Example: chart.options = { responsive: true, plugins: { title: { display: true, text: 'Chart.js' } }, scales: { x: { display: true }, y: { display: true } } }; chart.update();
Add data to chart
To add data to a chart, push a new label to chart.data.labels and push new data values to each dataset's data array, then call chart.update(). Example: chart.data.labels.push(label); chart.data.datasets.forEach((dataset) => { dataset.data.push(newData); }); chart.update();
Remove data from chart
To remove data from a chart, use pop() on chart.data.labels and pop() on each dataset's data array, then call chart.update(). Example: chart.data.labels.pop(); chart.data.datasets.forEach((dataset) => { dataset.data.pop(); }); chart.update();
Inaccessible fallback content about browser support
Using generic fallback text like 'Your browser does not support the canvas element.' does not provide meaningful accessibility for screen readers, as it does not describe the chart content.
Inaccessible canvas without role or aria-label
A canvas element without an accessible name or role attribute is inaccessible to screen readers.
Accessible canvas with ARIA label and role
To make a canvas element accessible, set the role attribute to 'img' and provide an aria-label attribute with a descriptive name. Example: <canvas id="goodCanvas1" width="400" height="100" aria-label="Hello ARIA World" role="img"></canvas>
Accessible canvas with fallback content
A canvas element can be made accessible by including text content as a fallback between the opening and closing canvas tags. This content serves as a text alternative. Example: <canvas id="okCanvas2" width="400" height="100"><p>Hello Fallback World</p></canvas>
Canvas accessibility requires ARIA attributes or fallback content
Chart.js charts render on canvas elements provided by the user. Canvas content is not accessible to screen readers by default. Accessibility must be added either by using ARIA attributes on the canvas element or by providing internal fallback content within the opening and closing canvas tags.
Pattern fills for accessibility
Pattern fills can help viewers with vision deficiencies such as color-blindness or partial sight more easily understand chart data.
Patternomaly library for generating patterns
The Patternomaly library can generate patterns to fill datasets. You can use pattern.draw() with pattern types like 'square', 'circle', 'diamond', and 'triangle' along with a color.
CanvasPattern example for dataset fill
This example shows how to fill a dataset with a pattern from an image: const img = new Image(); img.src = 'https://example.com/my_image.png'; img.onload = () => { const ctx = document.getElementById('canvas').getContext('2d'); const fillPattern = ctx.createPattern(img, 'repeat'); const chart = new Chart(ctx, { data: { labels: ['Item 1', 'Item 2', 'Item 3'], datasets: [{ data: [10, 20, 30], backgroundColor: fillPattern }] } }); };
Patternomaly example
This example shows how to use Patternomaly to generate patterns: const chartData = { datasets: [{ data: [45, 25, 20, 10], backgroundColor: [ pattern.draw('square', '#ff6384'), pattern.draw('circle', '#36a2eb'), pattern.draw('diamond', '#cc65fe'), pattern.draw('triangle', '#ffce56') ] }], labels: ['Red', 'Blue', 'Purple', 'Yellow'] };
Per-dataset color example
This example shows how to set colors for multiple datasets: const data = { labels: ['A', 'B', 'C'], datasets: [ { label: 'Dataset 1', data: [1, 2, 3], borderColor: '#36A2EB', backgroundColor: '#9BD0F5' }, { label: 'Dataset 2', data: [2, 3, 4], borderColor: '#FF6384', backgroundColor: '#FFB1C1' } ] };
Color elements in charts
Charts support changing colors for geometric elements (background and border colors) and textual elements (font color). The canvas background can also be changed.
Color format notations
Colors can be specified as strings in the following notations: Hexadecimal (e.g., #36A2EB or #36A2EB80 with transparency), RGB/RGBA (e.g., rgb(54, 162, 235) or rgba(54, 162, 235, 0.5)), and HSL/HSLA (e.g., hsl(204, 82%, 57%) or hsla(204, 82%, 57%, 0.5)).
Default colors in Chart.defaults
Default colors are defined in Chart.defaults with the following properties: backgroundColor defaults to rgba(0, 0, 0, 0.1), borderColor defaults to rgba(0, 0, 0, 0.1), and color (font color) defaults to #666.
Reset default colors
You can reset default colors by updating Chart.defaults.backgroundColor, Chart.defaults.borderColor, and Chart.defaults.color properties with new color values.
Per-dataset colors
For charts with multiple datasets, you can set backgroundColor and borderColor properties for each individual dataset to make them distinguishable.
CanvasPattern and CanvasGradient colors
Instead of string colors, you can pass CanvasPattern or CanvasGradient objects to color properties to achieve special effects.
Specific font options override global settings
More specific font properties defined in the chart config override the global Chart.defaults.font settings. For example, font settings in plugins.legend.labels.font will override the global font settings for legend labels.
Missing fonts display incorrectly
If a font is specified for a chart but does not exist on the system, the browser will not apply the font and odd fonts may appear in the chart. Check that the font exists on your system if you notice unexpected font rendering.
Loading fonts requires chart update
If a font is not cached and needs to be loaded, charts using the font must be updated once the font has loaded. This can be accomplished using the Font Loading APIs from MDN.
Global font settings location
Global font settings that apply to all text on a chart are stored in Chart.defaults.font. These global settings only apply when more specific options are not included in the config.
Font style does not apply to tooltip and chart title
The global font style setting does not apply to tooltip title or footer, and does not apply to chart title.
Font configuration reference
The Chart.defaults.font object has the following properties: family (string, default "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"), size (number in px, default 12, does not apply to radialLinear scale point labels), style (string, default 'normal', does not apply to tooltip title/footer or chart title, follows CSS font-style options: normal, italic, oblique, initial, inherit), weight (normal | bold | lighter | bolder | number, default undefined, see MDN for details), lineHeight (number or string, default 1.2, see MDN for details).
Global font override example
This example shows how to set a global font size of 16px, but override it to 14px specifically for legend labels: Chart.defaults.font.size = 16; let chart = new Chart(ctx, { type: 'line', data: data, options: { plugins: { legend: { labels: { font: { size: 14 } } } } } });
Data property formats overview
The data property of a dataset can be passed in various formats: Primitive arrays of numbers, Array of arrays/tuples, Object arrays with x/y properties, Objects with custom properties, or plain Objects with key-value pairs. By default, data is parsed using the associated chart type and scales.
Labels array requirements
The labels property of the main data object must contain the same number of elements as the dataset with the most values. These labels are used to label the index axis (default x axis). Labels must be provided in an array and can be of type string or number. For multiline labels, provide an array with each line as one entry.
Primitive array data format
When data is an array of numbers like [20, 10], values from the labels array at the same index are used for the index axis (x for vertical charts, y for horizontal charts). Example: data: [20, 10] with labels: ['a', 'b'] uses 'a' for 20 and 'b' for 10.
Dataset Configuration table
Dataset configuration options: | Name | Type | Description | | label | string | The label for the dataset which appears in the legend and tooltips. | | clip | number or object | How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. 0 = clip at chartArea. Can be configured per side: clip: {left: 5, top: false, right: -2, bottom: 0} | | order | number | The drawing order of dataset. Also affects order for stacking, tooltip and legend. | | stack | string | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). Defaults to dataset type. | | parsing | boolean or object | How to parse the dataset. Can be disabled with parsing: false. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. | | hidden | boolean | Configure the visibility of the dataset. Using hidden: true will hide the dataset from being rendered in the Chart. |
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).
Custom property parsing in datasets
Data objects can use custom properties beyond x and y. Use the parsing option with xAxisKey and yAxisKey to specify which properties to use. For nested properties, use dot notation like 'nested.value'. If a key name contains a dot, escape it with double backslash like 'data\\.key'.
Pie, doughnut, radar, polarArea parsing with key
When using pie, doughnut, radar, or polarArea chart types with custom property data, the parsing object should have a key property that points to the value to extract from each data object. Example: parsing: {key: 'nested.value'} for data like [{id: 'Sales', nested: {value: 1500}}].
Disabling parsing
Parsing can be disabled by specifying parsing: false at the chart options or dataset level. When parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. The values provided must be parsable by the associated scales or in the internal format of the associated scales.
Plain object data format
When data is a plain object like {January: 10, February: 20}, the property name is used for the index scale and the value for the value scale. For vertical charts, the index scale is x and value scale is y.
Object array data format
When data is an array of objects like [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}], each object has x and y properties. The x property can be numeric, a date string like '2016-12-25', or a category string like 'Sales'. This is the internal format used for parsed data.
Null values for skipped data points
null can be used in data values to skip points or create gaps in charts.
Example: Multiple datasets with custom property parsing
const data = [{x: 'Jan', net: 100, cogs: 50, gm: 50}, {x: 'Feb', net: 120, cogs: 55, gm: 75}]; const cfg = { type: 'bar', data: { labels: ['Jan', 'Feb'], datasets: [{ label: 'Net sales', data: data, parsing: { yAxisKey: 'net' } }, { label: 'Cost of goods sold', data: data, parsing: { yAxisKey: 'cogs' } }, { label: 'Gross margin', data: data, parsing: { yAxisKey: 'gm' } }] }, }; This example shows how to use multiple datasets with the same data array but extract different properties for each dataset using the parsing yAxisKey option.