The 2019 rewrite of Carbon Charts (and migration instructions)
Hi ✋, thank you for your interest in the Carbon Charts library. 🙂
We recently spent three months rewriting the codebase, and here’s why:
- We realized that shipping a set of not-so-highly-customizable components won’t cut it for our users. We understand that users who have data visualization needs work across a countless range of products that involve various types of audience, circumstances and use cases.
- We wanted to enable the development of custom charting layouts, graphs and, components.
- We needed to put in place a fully typed architecture (thanks to Typescript)
- We needed a way for you to be able to customize all the high-level default configurations to a chart.
Long story short, this work was completed on October 24, and we deployed v0.16.10 including the fundamentals of everything I mentioned above:
Carbon Charts now functions as a robust data-visualization framework in addition to being a library of pre-defined charting components.
Our goals moving forward:
- Ongoing compliance with the Carbon Design System data-visualization guidelines.
- Enhanced documentations and sample code.
- Richer wrapper layer exposed to frameworks.
Migration instructions from versions <0.16.10:
1. Vanilla bundle name change
If you are using the Vanilla package (@carbon/charts ) through a CDN, you’d need to start using bundle.js instead of index.umd.js
bundle.js still includes a UMD bundle, and will automatically be located by your bundler as the main file to import when importing modules from the@carbon/charts alias.
2. Styles
Update your imports of @carbon/charts/style.css to @carbon/charts/styles.css .
3. Theming
We no longer ship all four themes included inside the main CSS bundle.
If using CSS:
@carbon/charts/styles.css(default Carbon White theme)@carbon/charts/styles-g10.css@carbon/charts/styles-g90.css@carbon/charts/styles-g100.css
If using SCSS:
Importing @carbon/charts/styles/styles.scss will include the default Carbon White themed styles in your application.
Using the $carbon--themeflag you’d be able to customize what theme you’d bundle onto your application:
@import "@carbon/themes/scss/themes";// $carbon--theme: $carbon--theme--g10;// $carbon--theme: $carbon--theme--g90;// $carbon--theme: $carbon--theme--g100;@import "@carbon/charts/styles/styles.scss";
4. Updated data format:
There have not been any breaking changes to the data format except for 1
You’d need to change all occurrences of backgroundColors to fillColors .
However, there is an addition to the data format, time-series data:
5. Updated options format:
We’ve tried to introduce as few breaking changes as we can to the exposed APIs and architectures that you will be using.
However, there are still a few breaking changes within the charting data & options to consider when migrating.
The scales field in the options has been renamed to axes , introducing a new, more powerful interface.
You will always need a primary and a secondary axis defined in our pre-defined chart components. They can be inter-used as long as there is 1 of each within the 4 axes that you can define within the axes field.
For more code samples refer to https://github.com/carbon-design-system/carbon-charts/tree/master/packages/core/demo/demo-data
Additionally, there are smaller changes in the charting options that you’ll notice in the link above…
e.g.:
{ legendClickable: true }becoming:
{
legend: {
clickable: true
}
}We’re currently working on a utility that’ll take care of the conversion of legacy charting options to the most recent version. The goal is to keep the tool up-to-date with future changes as well to ensure compatibility at all times 💯.
6. Class name changes
This is only the case for the former BarChart class.
BarChart => SimpleBarChart, StackedBarChart, GroupedBarChart
We initially used the BarChart class to expose a chart that would be able to draw simple bars as well as stacked and grouped bars.
In the rewrite in we’ve removed the class and replaced it with the 3 new classes SimpleBarChart , StackedBarChart & GroupedBarChart.
This eliminates irrelevant logic, makes the bar chart logic more readable and helps us define interfaces that describe the different behaviors of the 3 types of bar chart.
In conclusion, I’d like to thank all the team members that made this rewrite effort a reality 🙌 👏:
And our fantastic design team:
And our awesome community contributors and users 🙂
