Getting Started

In this guide, we are going to show you how to get started with C3.


1. Setup

Download the latest version here:

Installing by Bower/Component is also available with the name c3.

Then, load the scripts and css:

<!-- Load c3.css -->
<link href="/path/to/c3.css" rel="stylesheet" type="text/css">

<!-- Load d3.js and c3.js -->
<script src="/path/to/d3.v3.min.js" charset="utf-8"></script>
<script src="/path/to/c3.min.js"></script>

C3 depends on D3, so please load D3 too.


2. Generate Chart

C3 generates a chart by calling generate() with the argument object, and an element including the chart will insert into the element specified as a selector in that argument as bindto.

Prepare the element to bind the chart:

<div id="chart"></div>

And, call generate() with arguments:

var chart = c3.generate({
    bindto: '#chart',
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ]
    }
});

C3 supports the asynchronous module definition (AMD) API. If you use RequireJS, you can load like this:

require.config({
  baseUrl: '/js',
  paths: {
    d3: "http://d3js.org/d3.v3.min"
  }
});

require(["d3", "c3"], function(d3, c3) {
  c3.generate({
    ...
  });
});

Then, you will see the chart:


Data can be loaded as columned data / rowed data / csv in URL.

There are serveral options to customize the chart and you can see those here:


3. Customize Chart

The chart can be customize by giving some options when generating. We will introduce some of them here.

1. Additional Axis

Introduce additional axis for data2. Add data.axes and axis.y2.show as follows:

var chart = c3.generate({
    bindto: '#chart',
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ],
      axes: {
        data2: 'y2' // ADD
      }
    },
    axis: {
      y2: {
        show: true // ADD
      }
    }
});

Then, the chart will be like this:


2. Show Axis Label

Show labels for each axis. Add axis.y.label and axis.y2.label as follows:

var chart = c3.generate({
    bindto: '#chart',
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ],
      axes: {
        data2: 'y2'
      }
    },
    axis: {
      y: {
        label: { // ADD
          text: 'Y Label',
          position: 'outer-middle'
        }
      },
      y2: {
        show: true,
        label: { // ADD
          text: 'Y2 Label',
          position: 'outer-middle'
        }
      }
    }
});

Then, the chart will be like this:


3. Change Chart Type

Show data2 as Bar chart. Add data.types as follows:

var chart = c3.generate({
    bindto: '#chart',
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ],
      axes: {
        data2: 'y2'
      },
      types: {
        data2: 'bar' // ADD
      }
    },
    axis: {
      y: {
        label: {
          text: 'Y Label',
          position: 'outer-middle'
        }
      },
      y2: {
        show: true,
        label: {
          text: 'Y2 Label',
          position: 'outer-middle'
        }
      }
    }
});

Then, the chart will be like this:


4. Format values

Format the values of each data. Add axis.y.tick.format as follows:

var chart = c3.generate({
    bindto: '#chart',
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ],
      axes: {
        data2: 'y2'
      },
      types: {
        data2: 'bar'
      }
    },
    axis: {
      y: {
        label: {
          text: 'Y Label',
          position: 'outer-middle'
        },
        tick: {
          format: d3.format("$,") // ADD
        }
      },
      y2: {
        show: true,
        label: {
          text: 'Y2 Label',
          position: 'outer-middle'
        }
      }
    }
});

Then, the chart will be like this:


More information about the options, please see Examples. (We'll add the reference soon)


4. Use APIs

By using APIs, you can update the chart after it's been rendered. We will introduce some of APIs here. APIs can be called through the object returned from generate().

1. Load Data

By using load() API, you can load data and update the chart dynamically as follows:

// var chart = c3.generate({ ... });

chart.load({
  columns: [
    ['data1', 300, 100, 250, 150, 300, 150, 500],
    ['data2', 100, 200, 150, 50, 100, 250]
  ]
});

If you push the button "Load" below, this code will run and the chart will be updated.


2. Unload Data

By using unload() API, you can unload the data dynamically as follows:

// var chart = c3.generate({ ... });

chart.unload({
    ids: ['data2', 'data3']
});

If you push the button "Unload" below, this code will run and the chart will be updated.


Please use unload param in load() API if load and unload need to run simultaneously. Please see this example.

3. Show/Hide Data

By using show() and hide() API, you can show/hide the data dynamically as follows:

// var chart = c3.generate({ ... });

chart.hide(['data2', 'data3']);
chart.show(['data2', 'data3']);

If you push the button "Show" and "Hide" below, this code will run and the chart will be updated.


The documentation about APIs is poor now, so please check the issues on github. There might be some hints about what you want to do. (We will add the document soon)


5. Customize Style

C3 give some classes for each element when generating. So, you can change the style of the elements by using those classes.

1. Line style

The lines have c3-line-[id] class, so this class can be used to define the style in css as follows:

#chart .c3-line-data2 {
  stroke-width: 5px;
}

Please check the class for each element if you want to change the style. Web Inspector would be useful. (We will add the document for class definition soon)


6. And More..

Please check the examples and the issues on github for more information. Sorry for the poor documentation. We're working on now and please give me some time. Thank you.