State of Chart.js & V3.0

[etimberg]

3.0 final is available

We're proud to announce that Chart.js 3.0.0 is now available. Get it with npm install --save chart.js

• Release notes
• npm
• Migration guide
• Docs
• API
• Samples

Overview

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 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
• Documentation migrated from GitBook to Docusaurus
• API Documentation generated and verified by TypeScript
• No more CSS injection
• Tons of bug fixes
• Tree shaking

In this issue we'll maintain a list of committed, nice-to-have, and proposed features for v3. Feedback from the community will help shape the prioritization for v3.

Committed Features

• Rollup configured for ES6+ babel translation (Add babel plugin for rollup & transform code #6555)
• Remove custom (Remove undocumented "custom" feature #6605)
• Remove all deprecated code
  • Most deprecated code has been removed. However grep -ri backward src still returns a handful of results. Also need to search the code for TODOs
• Prefix all private methods with underscore
• Make ticks objects (Consider making ticks objects #5019) (or not? should we revert? see Remove ticksToTimestamps and change ticks to numbers #6791)
• Remove moment from package.json (Remove moment from dependencies #6745), move the moment adapter to an external project, and remove the rollup optional plugin
• Remove zeroLineIndex feature and replace with function based axis properties (Remove zeroLineIndex functionality #6697 & Allow functions to be specified for scale grid line options #6700)
• Change require to import, adopt ES6 classes, use const / let, etc.
• Scale cleanup
  • Change axis options from an array to an object keyed by ID (Convert axis options from arrays to objects #6773)
  • Cleanup getPixelForTick (getPixelForTick is confusing and possibly inconsistent #6715)
• Performance Improvements
  • Accept data in a format that doesn't require parsing (Consider new format for passing data in #6696)
  • Improve performance of finding hovered element (Improve hover performance #6716)
  • Split _options out of _model. Creating _model is expensive right now, since it's done for each data point. However, _options does not need to be recreated for each data point unless scriptable options are being used. Thus by just using _options directly instead of copying it into _model we would be much more performant (Rewrite animation logic #6845)
  • Reduce number of objects created (e.g. _view and _model) when animation is disabled (e.g. Performance optimizations when animations are disabled #6710).
• Make beginAtZero default be true for bar chart (Change scale.beginAtZero default to true #5939)
• Cleanup options (Rationalize option names #5233)
  • Remove element options and remove global from options namespace (Global datasets options thought #6684 Remove global from defaults #6893)
  • Standardize on using degrees for angles (Polar area: startAngle in degrees, 0 at top. #6936)
• Migrate docs from GitBook to Docusaurus (Migrate from GitBook to Docusaurus #7295)
• Support tree shaking / individual module imports (v3: consider changing export logic for esm modules #7371)
• Leverage index / value concepts
  • Remove horizontalBar and make all charts capable of being horizontal (Replace horizontalBar with indexAxis: 'y' #7144)

Proposed / Nice to Have Features

• Scale cleanups
  • Improve the scale interface & document how to use it
  • Investigate normalizing options.scales and option.scale keys for all chart types
• Performance Improvements
  • Support drawing charts without creating elements possibly as external chart type (fastline controller #6881)
  • When the tooltip and other hover actions are disabled, the chart should not be redrawn when hovering on it. This would make external custom html tooltips massively faster. Along with this, consider making the default tooltip be an external tooltip (Provide out-of-the-box HTML tooltip capability #7195 (comment))
  • Make sure the tooltip listener only applies to the chart area and not the whole canvas (Upgrade benchmark to Chart.js 3.0.0-alpha.2 leeoniya/uPlot#277 (comment))
• Cleanup options (Rationalize option names #5233)
  • Remove overrides of _resolveDataElementOptions and _resolveDatasetElementOptions (Option resolution with proxies #8374)
  • Make _dataElementOptions an array in all controllers (i.e. line and radar). (Option resolution with proxies #8374)
  • Ensure user-specified options are applied after defaults. Delete _config and have just a single object holding resolved options (Option resolution with proxies #8374)
  • Make chart.options private and immutable (user should not directly edit, but should pass in new config to merge)
  • Cleanup interactions options (Add interaction options #7922)
• Leverage index / value concepts
  • Bar / rectangle cleanup (Consider replacing rectangle x/y with index/value #6760)
• Make drawing clearer
  • Investigate making drawings sharper
• Consider renaming axis label to axis title to differentiate from the tick labels
• Improve log scale tick generation (log scale step size too large #7332)
• Bar chart
  • Allow specifying pixels between bars (e.g. 1 px space and fill the rest). Right now it can only be a percentage
• Ideas from @simonbrunel: Chart.js 3.pdf

Won't do

• Can we move hidden elements to plugin? (Remove unnecessary checks for hidden data #6255)
• Split out the time scale into it's own package
• Consider removing data from config so that we have datasets, labels, and options as first level properties. We agreed that data.datasets.data is confusing, but every chart would need to be updated if we changed this and all StackOverflow answers would be outdated

How can you help?

• Provide feedback on which issues you would like prioritized for v3
• Test out alpha & beta releases as they become available. The alpha release is quite stable though we have found a few issues. Thanks to the folks that reported them! Here's a list of known issues
• Volunteer time to help improve the project

[sebiniemann]

I would like to work on

• Change require to import

Should I do this within the current code base (may take a day for the whole projet, I could start during the upcomming weekend) aka master?

[etimberg]

@sebastianniemann I think that's the best way to do it. We've already started merging breaking changes to master. If we need to do 2.9.x hotfixes we'll do that in a separate branch.

@benmccann @kurkle thoughts?

[benmccann]

Yes, go for it! I would love that :-)

[leeoniya]

Chart.js currently struggles with hover / live value display in large datasets. Might want to also look into this.

https://github.com/leeoniya/uPlot#performance

[benmccann]

Good suggestion! I filed #6716 to discuss and track that issue

[kurkle]

Should we consider dropping IE support? It would make some new things available:
Proxy - for data change detection
Map - for array uniqueness (if we can't get rid of it). Its quite a lot faster really compared jsperfs test of it. (uPlot arrayUnique in ~25ms isntead of ~150ms)

Another thing worth exploring is ResizeObserver. That could be used, instead of current implementation, if supported.

[benmccann]

As much as I'd love to drop IE, I think there are still too many IE 11 users. The main website I'm working on right now has ~5% of traffic in IE. But it'd be great to use Proxy, Map, or ResizeObserver when they're available and fallback to the current methods for IE!

[etimberg]

I recall ResizeObserver not working entirely for div resizing last time I investigated a few years ago.

[leeoniya]

as another datapoint, our IE11 traffic for the past 2 weeks has been 2.65%, it was 5.62% for the same period last year. (usa, ecommerce, home remodeling industry).

at some point, as a lib/web author you gotta ask yourself whether maintaining IE11 compat further delays its inevitable death.

[benmccann]

For Map, you can just use it directly and have babel take care of polyfilling it.

[davidswinegar]

Hello - is there any movement towards enabling Chart.js to be used inside a web worker controlling an offscreencanvas? I've seen this issue: #5355. If it's appropriate I'd be interested in taking on the necessary work to get it working. Let me know if there's anywhere I should get started! I'll probably be submitting some speculative PRs for this soon.

Context: a major project that we'll be taking on for https://github.com/cruise-automation/webviz in the near future is moving our Chart panel behind a web worker for performance reasons. We use Chart.js currently and love it, and we'd like to keep using it.

[etimberg]

@davidswinegar I haven't tried anything yet. However, I think the limitations would be similar to those for server-side rendering. I know that has been done a fair bit with Chart.js (example: https://github.com/shellyln/chart.js-node-ssr-example).

I think you would need to disable resizing since that needs access to the DOM. I also don't know if window.devicePixelRatio is available in a worker. One thing that would need dev work would be switching the canvas context on an existing chart. I think this would let you do:

1. Render initial chart offscreen
2. Copy the offscreen canvas image to the onscreen canvas
3. Point the chart instance to the onscreen canvas to allow interactivity

I am curious though, are you hitting performance bottlenecks in Chart.js itself? If so, you might like to try the latest code from master (will eventually release as v3) because @kurkle and @benmccann have been doing lots of performance improvements.

[davidswinegar]

@etimberg thanks for the info! I am hitting performance issues in Chart.js, though I'm not sure if it's because of the library itself or the fundamental cost of drawing on the canvas. I'll do some benchmarks on the code that's in master and see how it affects us.

[etimberg]

Sounds good. There are lots of breaking changes in master, and docs on those are https://www.chartjs.org/docs/master/getting-started/v3-migration.html

[benmccann]

Most of the work in 2.x is not related to drawing on the canvas. I think most of that work can be removed. A good chunk already has been. After that's done I don't know if web workers would still provide benefit?

If you use the version from master, which is much faster please see the updated performance documentation to make sure you set options that result in maximum performance. Most of the work has tested on improving line chart performance though many of those improvements help all charts generally. I'd be interested in any feedback you have if you try out what's in master (see the migration guide as there have been numerous changes) and how far off we are to meet your goals.

[davidswinegar]

I tried the version in master and followed the performance documentation and I definitely noticed an improvement! Thanks for the feedback., Our product requirements mean that this improvement won't be enough, though, and that we'll still have to put Chart.js behind a web worker. I'll take this to Slack to work through some approaches on the details.

For context, we're updating 5+ charts many times a second and attempting to play back data in real-time without dropping any data; our performance characteristics need to be closer to games than to analytics web applications. Regardless of how performant Chart.js is, passing data over a web-worker connection and drawing it from there is necessary for us to squeeze every cycle out of the browser - if we were writing our own performance optimized canvas library we'd still have to do this.

[leeoniya]

@davidswinegar if these are line charts, you can try uPlot to get an idea of what's possible in terms of performance.

[benmccann]

I'm aiming to get about another 10x increase in performance. I have a handful of pending PRs that are all geared towards improving performance. I'm happy discuss the web worker approach or any other perf ideas over Slack as you suggested

[leeoniya]

I'm aiming to get about another 10x increase in performance.

😮 that would be impressive! uPlot is currently at 40ms, Chart.js master is 305ms. 10x faster would be 25% faster than uPlot and i'm not really sure where i can shave a full 10ms!

[davidswinegar]

@leeoniya your numbers look impressive! I think that Chart.js is the choice for us because of support for panning & zooming, and more chart types, but I'll keep uPlot in mind.

[benmccann]

Re 10x: It depends which charts you're drawing, what dates you're comparing (e.g. master now is already significantly faster than master yesterday), etc. Plus, I said "about" so if I get 7-8x faster and round up I'll be pretty happy... ;-)

@davidswinegar depending how much you want to experiment you can try grabbing my two pending PRs. It gets Chart.js line charts from 550ms down to 100ms on the uPlot benchmark on my machine compared to 70ms for uPlot: #6881 (comment). The "fastline" PR may be released as an external plugin rather than being merged into core, but should allow you to use other plugins with it still such as zoom/pan, etc. I'm curious what other chart types and scale types you use. I've been most focused on optimizing the time scale and line charts since that's what I use most myself

[stockiNail]

options.onClick is now limited to the chart area

I've seen that going to v3, the onClick function will be limited to chart area.
I've implemented specific functions in order to catch click events on axes and title because it could be helpful.

Do you think this new feature could be re-thought again?
Will this reduction of events scope apply to onHover as well?

[kurkle]

You can hook on the canvas click even directly to catch all clicks.
onHover might be changed too, it should only fire when an element is hovered.
Workaround will be similar, you can use mousemove event of the canvas.

[stockiNail]

You can hook on the canvas click even directly to catch all clicks.
onHover might be changed too, it should only fire when an element is hovered.
Workaround will be similar, you can use mousemove event of the canvas.

But in this case you have more listeners instead of one. It sounds redundant, in my opinion.
Anyway if you are going to this implementation, there is not other way, I guess.
What I can suggest here is if you are limiting the scope of click event to chart area, it could be better to do the same for onHover as well, to be consistent.
That means all events (defined at options level) have got chart area scope.

[xr0master]

@Cristy94 I'm using alfa.2 for production too. I think the best docs for v3 at the moment is migration doc: https://www.chartjs.org/docs/next/getting-started/v3-migration

[darkship]

With the alpha2, I was able to reproduce about 20 of my company's charts. Bars, pies and lines with different aspects of legends, title, tooltips, stacked, etc...
One of the chart had so many lines and points that nearly every pixel had a tooltip but it was still smooth.

I had some issue with the "pie" type where having the scaling configuration from "line" made it explode.

Can I already consider the API as stable? I didn't see many changes on the API in the last months (due to COVID19 effect maybe?)

[xr0master]

A bit offtopic and advertising. I wrote a React wrapper for chat.js version 3. I use it for production.
https://www.npmjs.com/package/chartjs-react
Maybe someone will come in handy.

P.S. Forgive me if this is not correct, I am not very familiar with the rules in open source projects.

@darkship the tooltips callbacks have been heavily modified. IMO

[Eonasdan]

I'm looking forward to being able to use chart.js v3 in my angular project. Hopefully ng2-charts will update and I'll be free of the new angular 10 warnings about commonjs/amd libs.

I'd like to throw my 2 cents about IE11 support and recommend that you drop support for it. Bootstrap 5 will no longer support among the many many sites that are dropping support for it. If people still need IE11 they should stay on chart v2 or they can use polyfills. Much like the BS 5 - IE11 discussion I agree that library's should no longer held back by IE11 and that forward momentum is only possible by dropping support for it.

[sakulstra]

Is there any date-adapter which is already ported to work with the beta-0?
Just tried upgrading a project of mine to test-run the beta, but it seems like the new import/register structure broke parts of the plugin ecosystem i'm relying on.

chartjs/chartjs-adapter-luxon#12 (comment)

[kurkle]

chartjs-adapter-date-fns@next

[xr0master]

Guys, please do not consider me arrogant, but there are plans for the version of Beta.2?
I'm really looking forward to it.

[etimberg]

@xr0master I was waiting until #7806 got in before cutting a new release.

[literakl]

#7806 was merged already in september.

[etimberg]

@literakl that released in v3.0.0-beta.2.

[godenji]

Question about tree shaking in v3.

Given the following:

Chart.js 3.0.0-beta.7
Angular 10.2.0
TypeScript 3.9.4
NodeJS v12.18.2

and a basic chart config:

import { Chart, Title } from `chart.js`

Chart.register(Title);

const chart = new Chart(ctx, {
    type: 'line',
    // data: ...
    options: {
        plugins: {
            title: { display: true, text: 'Chart Title' }
        },
        scales: { y: { stacked: false } }
    }
})

source-map-explorer shows Chart.js weighing in at 148KB, just 20KB less than Chart.js.min -- is this to be expected, or should users be seeing a (much) greater reduction in bundle size given the above setup?

[elitastic]

Is there an expected approximate release date for ChartJs 3?

[Homand-Cindy]

I'm also interested to know if there is an expected approximate release date for ChartJs 3, please?

[derwaldgeist]

Is there an adapter for dayjs? I want to get rid of momentjs in my mobile app, as it is way too big. But I would love to keep my existing API calls in place, so I decided for dayjs in favor of luxon. It would be great if chartjs would support this, too. This makes it very easy to migrate, and it should be easy to implement, as the API is pretty much the same as momentjs.

[etimberg]

No specific date yet @Homand-Cindy. #8008 is what we're trying to get done before the release.

@derwaldgeist I think you could easily create your own adapter for dayjs based off the moment adapter source https://github.com/chartjs/chartjs-adapter-moment

[aried3r]

@derwaldgeist, there's a few on npm, however the oldest I believe is unmaintained. The other two with recent releases also support Chart.js v3 I believe. https://www.npmjs.com/search?q=chartjs-adapter-dayjs

But we also did what @etimberg said and adapted the official moment adapter. However that was two years ago.

[Eonasdan]

Creating a dayjs adapter should be extremely simple since dayjs uses most of the same method names as moment. First thing I'd do is is just do a find and replace and see what happens

[etimberg]

I have a project using Chart.js v3 right now. I just inlined the luxon adaptor since the repo wasn't updated at the time. Works quite well and was easy to set up

[derwaldgeist]

I think you could easily create your own adapter for dayjs based off the moment adapter source

Yes, I was thinking about doing that.

The other two with recent releases also support Chart.js v3 I believe. https://www.npmjs.com/search?q=chartjs-adapter-dayjs

Thanks for the info!

[boddunan]

No specific date yet @Homand-Cindy. #8008 is what we're trying to get done before the release.

Looks like most of the PRs are already merged, any info on what is holding before the v3 stable release?

[kurkle]

@boddunan its getting close. I think #8332 is probably the last breaking change. There will most likely be one more beta and one or more release canditates before release.

[etimberg]

The first release candidate, v3.0.0-rc was released today.