C3 is a JavaScript library for data visualization in HTML5 built using D3. Source is available on GitHub.

## Notable visualizations include:

- Line / Area Graphs
- Bar Charts
- Stacked Graphs
- Pie / Donut Charts
- Scatter Plots
- Swimlanes
- Flame Chart Timeline
- Sunburst
- Sankey Flow Graph
- Butterfly (caller/callee) Flow Graph
- Legends
- Data Tables

## Notable features include:

- Declarative style API.
- Flexibility with dataset organization. Use your own structures and describe their shape via accessor functions.
- Layering mechanism for composability of different data in the same chart.
- Compatible with animation for linked and dynamic datasets.
- Lots of styling options by exposing CSS directly.
- Extensible for custom user interaction by exposing DOM events.
- Extensible with custom functionality.
- Some visualizations contain built-in support for dealing with large datasets.
- Compatible with Crossfilter (example)

## Overview

So why another JavaScript visualization library? Charts can always be made with a template engine, by directly manipulating the DOM with the raw W3C DOM JavaScript API, or by using a library such as JQuery. But, we don't want to have to re-invent the wheel every time. The D3 (Data-Driven Documents) library is a powerful framework for DOM manipulation. However, it is really best thought of as a toolbox, as it does not contain any built-in charts per-se. You can use it to help create all sorts of custom visualizations, but there is a steep learning curve and lots of repitition required to recreate common charts. At a higher-level, there are a plethra of JavaScript visualization libraries availble with a wide range of built-in charts you can grab and start using off the shelf. For various projects I've tried to use them and generally ran into problems such as them requiring the data to be laid out in a certain way, or missing functionality I needed without a good way to extend them. Out of this frustration, C3 was born.

C3 is a collection of data visualizations leveraging the D3 toolbox. It provides these charts with a simple declarative API to easily get started. However, it does not bury the implementation in an abstraction layer that loses the major benefits of D3. Data sets can generally be provided as an array of objects, but no restriction is made on the format of the object. Accessor functions can be defined to describe the shape and how to get what the chart needs from the data set, or to provide arbitrary logic to get the data from other locations. C3 relies on and exposes the raw CSS styles and DOM events to allow a lot of flexibility in styling and interactive behaviour. Because it exposes raw styles and events it does not restrict the styling or events that your browser supports. As new styles or events are offered by browser vendors they are automatically supported. If that's not enough, C3 also provides a mechanism for extending charts with new functionality if the built-in features are insufficient.

Check out the examples as a tutorial of how to create some simple visualizations. Or, jump to the World Bank example for a more complex scenario with multiple linked charts for a relational data set that can be dynamically filtered across multiple dimensions. There is also an API overview and API reference.

Note that these documentation pages are bundeled with the source repository. Therefore, they are intentially kept simple barebones documentation and examples without pulling in too many additional dependencies to look pretty.

# Usage

To use C3, simply include `d3.js`, `c3.js`, and `c3.css`:

>     <script src="d3.js"></script>
>     <script src="c3.js"></script>
>     <link rel="stylesheet" href="c3.css">

And then include any desired C3 visualizations. For example:

>     <script src="c3-table.js"></script>
>     <script src="c3-plot.js"></script>
>     <script src="c3-layers.js"></script>
>     <script src="c3-legend.js"></script>
>     <script src="c3-polar.js"></script>
>     <script src="c3-graph.js"></script>

Please see the Examples and API Documentation for more details.

### NPM Package `q3`

Alternatively, C3 is now available as an NPM package. Unfortunately, betweeen the time when this project started and when it was approved for open source, the NPM package name `c3` was taken by another project. Therefore, the package is currently published under `q3` while pending renaming consideration. In your `package.json` you can include it via:

>         "dependencies": {
>             "q3": "^0.1.4"
>         }

An initial main entry point has been included so you can require the package. For example, if you are using a browser or transpiled language which supports ES6 modules, you can use:

>     import d3 from 'd3';
>     import c3 from 'q3';
>     require('q3/css/c3.css');

### Dependencies

D3 is the only hard dependency for C3. Many thanks to Mike Bostok for creating this wonderful toolbox. Be sure to include the D3 script before including the C3 script.

For additional performance, the Crossfilter library can also be included before C3 to improve some sorting operations.

### TypeScript

C3 is also bundeled with a TypeScript definitions file `c3.d.ts` for those who would like to use TypeScript.

Type definitions are not currently published for Flow. Please let me know if there is interest.

# Examples

- Examples

Examples of various C3 charts and tables. They are useful to demonstrate or test functionality or as a learning tutorial. The examples start simple to cover each visualization type and build for a more complex tutorial.

# Documentation

- API Overview
- API Reference - In the reference, the Variables Summary sections list the set of options that can be specified for each visaulization or layer type via the constructor or render options object parameter.

# Compatibility

C3 has been tested with Chrome, IE, and Firefox. However, not all browsers fully support all features and so there may be some styling and placement differences. Performance is definitely best with Chrome.

Notably, IE does not support canvas swimlanes embedded in an SVG chart, vector scaling for zoomable line charts, and placement of labels in the center of scatter plot circles.

Also, please note that by default some IT departments set a policy which defaults IE to an old "compatibility" mode for internal sites where most things don't work. Either each user has to disable this compatibility mode or you can add the following in your html header to request to disable compatibility mode:

> `<meta http-equiv="X-UA-Compatible" content="IE=edge" />`

# License

The Configurable Chart Collection has been released under the BSD 3-Clause open source license.