The 2019 rewrite of Carbon Charts (and migration instructions)

Dec 9, 2019 · 4 min read

Hi ✋, thank you for your interest in the Carbon Charts library. 🙂

We recently spent three months rewriting the codebase, and here’s why:

  1. 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.
  2. We wanted to enable the development of custom charting layouts, graphs and, components.
  3. We needed to put in place a fully typed architecture (thanks to Typescript)
  4. 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:

  1. Ongoing compliance with the Carbon Design System data-visualization guidelines.
  2. Enhanced documentations and sample code.
  3. 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 ( ) through a CDN, you’d need to start using instead of

still includes a UMD bundle, and will automatically be located by your bundler as the main file to import when importing modules from the alias.

2. Styles

Update your imports of to .

3. Theming

We no longer ship all four themes included inside the main CSS bundle.

If using CSS:

  • (default Carbon White theme)

If using SCSS:

Importing will include the default Carbon White themed styles in your application.

Using the 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 to .

However, there is an addition to the data format, time-series data:

Find simpleBarTimeSeriesData under

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 field in the options has been renamed to , 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 and a 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 field.

Currently supported scale types for an axis

For more code samples refer to

Additionally, there are smaller changes in the charting options that you’ll notice in the link above…


{ legendClickable: true }


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 class.

BarChart => SimpleBarChart, StackedBarChart, GroupedBarChart

We initially used the 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 , &

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 🙂


Carbon is the design system for IBM software products. It is a series of individual styles, components, and guidelines used for creating unified UI.


Written by


Fullstack Dreamer


Carbon is the design system for IBM software products. It is a series of individual styles, components, and guidelines used for creating unified UI.

More From Medium

More on Carbon Design System from _carbondesign

More on Carbon Design System from _carbondesign

Seven new UX patterns for Carbon

Jan Child
Jan 9 · 2 min read


More on Carbon Design System from _carbondesign

More on Carbon Design System from _carbondesign

More on Carbon Design System from _carbondesign

Help build Carbon — Hacktoberfest 2019

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade