The 2019 rewrite of Carbon Charts (and migration instructions)
Tags: Carbon Design System, Data Visualization, JavaScript, Dataviz, Charts

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)

(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--theme flag 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:

Find simpleBarTimeSeriesData under https://github.com/carbon-design-system/carbon-charts/blob/master/packages/core/demo/demo-data/bar.ts

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.

AxesOptions interface within the charting options

AxisOptions interface defining the customizable attributes of an axis

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.

Currently supported scale types for an axis

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.