Contributions to Chart.js are welcome and encouraged, but please have a look through the guidelines in this document before raising an issue, or writing code for the project.\n
\n
\n
Using issues\n
------------\n
\n
The [issue tracker](https://github.com/nnnick/Chart.js/issues) is the preferred channel for reporting bugs, requesting new features and submitting pull requests.\n
\n
If you\'re suggesting a new chart type, please take a look at [writing new chart types](https://github.com/nnnick/Chart.js/blob/master/docs/06-Advanced.md#writing-new-chart-types) in the documentation, and some of the [community extensions](https://github.com/nnnick/Chart.js/blob/master/docs/06-Advanced.md#community-extensions) that have been created already.\n
\n
To keep the library lightweight for everyone, it\'s unlikely we\'ll add many more chart types to the core of Chart.js, but issues are a good medium to design and spec out how new chart types could work and look.\n
\n
Please do not use issues for support requests. For help using Chart.js, please take a look at the [`chartjs`](http://stackoverflow.com/questions/tagged/chartjs) tag on Stack Overflow.\n
\n
\n
Reporting bugs\n
--------------\n
\n
Well structured, detailed bug reports are hugely valuable for the project.\n
\n
Guidlines for reporting bugs:\n
\n
- Check the issue search to see if it has already been reported\n
- Isolate the problem to a simple test case\n
- Provide a demonstration of the problem on [JS Bin](http://jsbin.com) or similar\n
\n
Please provide any additional details associated with the bug, if it\'s browser or screen density specific, or only happens with a certain configuration or data.\n
\n
\n
Pull requests\n
-------------\n
\n
Clear, concise pull requests are excellent at continuing the project\'s community driven growth. But please review [these guidelines](https://github.com/blog/1943-how-to-write-the-perfect-pull-request) and the guidelines below before starting work on the project.\n
\n
Guidlines:\n
\n
- Please create an issue first:\n
- For bugs, we can discuss the fixing approach\n
- For enhancements, we can discuss if it is within the project scope and avoid duplicate effort\n
- Please make changes to the files in [`/src`](https://github.com/nnnick/Chart.js/tree/master/src), not `Chart.js` or `Chart.min.js` in the repo root directory, this avoids merge conflicts\n
- Tabs for indentation, not spaces please\n
- If adding new functionality, please also update the relevant `.md` file in [`/docs`](https://github.com/nnnick/Chart.js/tree/master/docs)\n
- Please make your commits in logical sections with clear commit messages\n
\n
Joining the Project\n
-------------\n
- Active committers and contributors are invited to introduce yourself and request commit access to this project. Please send an email to hello@nickdownie.com or file an issue. \n
\n
License\n
-------\n
\n
By contributing your code, you agree to license your contribution under the [MIT license](https://github.com/nnnick/Chart.js/blob/master/LICENSE.md).\n
<value><string>Copyright (c) 2013-2015 Nick Downie\n
\n
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n
\n
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n
\n
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n
*Simple HTML5 Charts using the canvas element* [chartjs.org](http://www.chartjs.org)\n
\n
## Documentation\n
\n
You can find documentation at [chartjs.org/docs](http://www.chartjs.org/docs/). The markdown files that build the site are available under `/docs`. Please note - in some of the json examples of configuration you might notice some liquid tags - this is just for the generating the site html, please disregard.\n
\n
## Bugs, issues and contributing\n
\n
Before submitting an issue or a pull request to the project, please take a moment to look over the [contributing guidelines](https://github.com/nnnick/Chart.js/blob/master/CONTRIBUTING.md) first.\n
\n
For support using Chart.js, please post questions with the [`chartjs` tag on Stack Overflow](http://stackoverflow.com/questions/tagged/chartjs).\n
\n
## License\n
\n
Chart.js is available under the [MIT license](http://opensource.org/licenses/MIT).\n
First we need to include the Chart.js library on the page. The library occupies a global variable of `Chart`.\n
\n
```html\n
<script src="Chart.js"></script>\n
```\n
\n
Alternatively, if you\'re using an AMD loader for JavaScript modules, that is also supported in the Chart.js core. Please note: the library will still occupy a global variable of `Chart`, even if it detects `define` and `define.amd`. If this is a problem, you can call `noConflict` to restore the global Chart variable to its previous owner.\n
\n
```javascript\n
// Using requirejs\n
require([\'path/to/Chartjs\'], function(Chart){\n
\t// Use Chart.js as normal here.\n
\n
\t// Chart.noConflict restores the Chart global variable to its previous owner\n
\t// The function returns what was previously Chart, allowing you to reassign.\n
To create a chart, we need to instantiate the `Chart` class. To do this, we need to pass in the 2d context of where we want to draw the chart. Here\'s an example.\n
// Get the context of the canvas element we want to select\n
var ctx = document.getElementById("myChart").getContext("2d");\n
var myNewChart = new Chart(ctx).PolarArea(data);\n
```\n
\n
We can also get the context of our canvas with jQuery. To do this, we need to get the DOM node out of the jQuery collection, and call the `getContext("2d")` method on that.\n
\n
```javascript\n
// Get context with jQuery - using jQuery\'s .get() method.\n
var ctx = $("#myChart").get(0).getContext("2d");\n
// This will get the first returned node in the jQuery collection.\n
var myNewChart = new Chart(ctx);\n
```\n
\n
After we\'ve instantiated the Chart class on the canvas we want to draw on, Chart.js will handle the scaling for retina displays.\n
\n
With the Chart class set up, we can go on to create one of the charts Chart.js has available. In the example below, we would be drawing a Polar area chart.\n
\n
```javascript\n
new Chart(ctx).PolarArea(data, options);\n
```\n
\n
We call a method of the name of the chart we want to create. We pass in the data for that chart type, and the options for that chart as parameters. Chart.js will merge the global defaults with chart type specific defaults, then merge any options passed in as a second argument after data.\n
\n
###Global chart configuration\n
\n
This concept was introduced in Chart.js 1.0 to keep configuration DRY, and allow for changing options globally across chart types, avoiding the need to specify options for each instance, or the default for a particular chart type.\n
\t// Boolean - whether or not the chart should be responsive and resize when the browser does.\n
\tresponsive: false,\n
\n
\t// Boolean - whether to maintain the starting aspect ratio or not when responsive, if set to false, will take up entire container\n
\tmaintainAspectRatio: true,\n
\n
\t// Boolean - Determines whether to draw tooltips on the canvas or not\n
\tshowTooltips: true,\n
\n
\t// Function - Determines whether to execute the customTooltips function instead of drawing the built in tooltips (See [Advanced - External Tooltips](#advanced-usage-external-tooltips))\n
\tcustomTooltips: false,\n
\n
\t// Array - Array of string names to attach tooltip events\n
The line chart requires an array of labels for each of the data points. This is shown on the X axis.\n
The data for line charts is broken up into an array of datasets. Each dataset has a colour for the fill, a colour for the line and colours for the points and strokes of the points. These colours are strings just like CSS. You can use RGBA, RGB, HEX or HSL notation.\n
\n
The label key on each dataset is optional, and can be used when generating a scale for the chart.\n
\n
### Chart options\n
\n
These are the customisation options specific to Line charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.\n
\n
```javascript\n
{\n
\n
\t///Boolean - Whether grid lines are shown across the chart\n
\tscaleShowGridLines : true,\n
\n
\t//String - Colour of the grid lines\n
\tscaleGridLineColor : "rgba(0,0,0,.05)",\n
\n
\t//Number - Width of the grid lines\n
\tscaleGridLineWidth : 1,\n
\n
\t//Boolean - Whether to show horizontal lines (except X axis)\n
\tscaleShowHorizontalLines: true,\n
\n
\t//Boolean - Whether to show vertical lines (except Y axis)\n
\tscaleShowVerticalLines: true,\n
\n
\t//Boolean - Whether the line is curved between points\n
\tbezierCurve : true,\n
\n
\t//Number - Tension of the bezier curve between points\n
\tbezierCurveTension : 0.4,\n
\n
\t//Boolean - Whether to show a dot for each point\n
\tpointDot : true,\n
\n
\t//Number - Radius of each point dot in pixels\n
\tpointDotRadius : 4,\n
\n
\t//Number - Pixel width of point dot stroke\n
\tpointDotStrokeWidth : 1,\n
\n
\t//Number - amount extra to add to the radius to cater for hit detection outside the drawn point\n
\tpointHitDetectionRadius : 20,\n
\n
\t//Boolean - Whether to show a stroke for datasets\n
\tdatasetStroke : true,\n
\n
\t//Number - Pixel width of dataset stroke\n
\tdatasetStrokeWidth : 2,\n
\n
\t//Boolean - Whether to fill the dataset with a colour\n
\tdatasetFill : true,\n
\t{% raw %}\n
\t//String - A legend template\n
\tlegendTemplate : "<ulclass=\\"<%=name.toLowerCase()%>-legend\\"><% for (var i=0; i<datasets.length;i++){%><li><spanstyle=\\"background-color:<%=datasets[i].strokeColor%>\\"></span><%if(datasets[i].label){%><%=datasets[i].label%><%}%></li><%}%></ul>"\n
\t{% endraw %}\n
\n
\t//Boolean - Whether to horizontally center the label and point dot inside the grid\n
\toffsetGridLines : false\n
};\n
```\n
\n
You can override these for your `Chart` instance by passing a second argument into the `Line` method as an object with the keys you want to override.\n
\n
For example, we could have a line chart without bezier curves between points by doing the following:\n
\n
```javascript\n
new Chart(ctx).Line(data, {\n
\tbezierCurve: false\n
});\n
// This will create a chart with all of the default options, merged from the global config,\n
// and the Line chart defaults, but this particular instance will have `bezierCurve` set to false.\n
```\n
\n
We can also change these defaults values for each Line type that is created, this object is available at `Chart.defaults.Line`.\n
\n
\n
### Prototype methods\n
\n
#### .getPointsAtEvent( event )\n
\n
Calling `getPointsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event.\n
\t// => activePoints is an array of points on the canvas that are at the same position as the click event.\n
};\n
```\n
\n
This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.\n
\n
#### .update( )\n
\n
Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.\n
\n
```javascript\n
myLineChart.datasets[0].points[2].value = 50;\n
// Would update the first dataset\'s value of \'March\' to be 50\n
myLineChart.update();\n
// Calling update now animates the position of March from 90 to 50.\n
```\n
\n
#### .addData( valuesArray, label )\n
\n
Calling `addData(valuesArray, label)` on your Chart instance passing an array of values for each dataset, along with a label for those points.\n
\n
```javascript\n
// The values array passed into addData should be one for each dataset in the chart\n
myLineChart.addData([40, 60], "August");\n
// This new data will now animate at the end of the chart.\n
```\n
\n
#### .removeData( )\n
\n
Calling `removeData()` on your Chart instance will remove the first value for all datasets on the chart.\n
\n
```javascript\n
myLineChart.removeData();\n
// The chart will remove the first point and animate other points into place\n
The bar chart has the a very similar data structure to the line chart, and has an array of datasets, each with colours and an array of data. Again, colours are in CSS format.\n
We have an array of labels too for display. In the example, we are showing the same data as the previous line chart example.\n
\n
The label key on each dataset is optional, and can be used when generating a scale for the chart.\n
\n
### Chart Options\n
\n
These are the customisation options specific to Bar charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.\n
\n
```javascript\n
{\n
\t//Boolean - Whether the scale should start at zero, or an order of magnitude down from the lowest value\n
\tscaleBeginAtZero : true,\n
\n
\t//Boolean - Whether grid lines are shown across the chart\n
\tscaleShowGridLines : true,\n
\n
\t//String - Colour of the grid lines\n
\tscaleGridLineColor : "rgba(0,0,0,.05)",\n
\n
\t//Number - Width of the grid lines\n
\tscaleGridLineWidth : 1,\n
\n
\t//Boolean - Whether to show horizontal lines (except X axis)\n
\tscaleShowHorizontalLines: true,\n
\n
\t//Boolean - Whether to show vertical lines (except Y axis)\n
\tscaleShowVerticalLines: true,\n
\n
\t//Boolean - If there is a stroke on each bar\n
\tbarShowStroke : true,\n
\n
\t//Number - Pixel width of the bar stroke\n
\tbarStrokeWidth : 2,\n
\n
\t//Number - Spacing between each of the X value sets\n
\tbarValueSpacing : 5,\n
\n
\t//Number - Spacing between data sets within X values\n
\tbarDatasetSpacing : 1,\n
\t{% raw %}\n
\t//String - A legend template\n
\tlegendTemplate : "<ulclass=\\"<%=name.toLowerCase()%>-legend\\"><% for (var i=0; i<datasets.length;i++){%><li><spanstyle=\\"background-color:<%=datasets[i].fillColor%>\\"></span><%if(datasets[i].label){%><%=datasets[i].label%><%}%></li><%}%></ul>"\n
\t{% endraw %}\n
}\n
```\n
\n
You can override these for your `Chart` instance by passing a second argument into the `Bar` method as an object with the keys you want to override.\n
\n
For example, we could have a bar chart without a stroke on each bar by doing the following:\n
\n
```javascript\n
new Chart(ctx).Bar(data, {\n
\tbarShowStroke: false\n
});\n
// This will create a chart with all of the default options, merged from the global config,\n
// and the Bar chart defaults but this particular instance will have `barShowStroke` set to false.\n
```\n
\n
We can also change these defaults values for each Bar type that is created, this object is available at `Chart.defaults.Bar`.\n
\n
### Prototype methods\n
\n
#### .getBarsAtEvent( event )\n
\n
Calling `getBarsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the bar elements that are at that the same position of that event.\n
\t// => activeBars is an array of bars on the canvas that are at the same position as the click event.\n
};\n
```\n
\n
This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.\n
\n
#### .update( )\n
\n
Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.\n
\n
```javascript\n
myBarChart.datasets[0].bars[2].value = 50;\n
// Would update the first dataset\'s value of \'March\' to be 50\n
myBarChart.update();\n
// Calling update now animates the position of March from 90 to 50.\n
```\n
\n
#### .addData( valuesArray, label )\n
\n
Calling `addData(valuesArray, label)` on your Chart instance passing an array of values for each dataset, along with a label for those bars.\n
\n
```javascript\n
// The values array passed into addData should be one for each dataset in the chart\n
myBarChart.addData([40, 60], "August");\n
// The new data will now animate at the end of the chart.\n
```\n
\n
#### .removeData( )\n
\n
Calling `removeData()` on your Chart instance will remove the first value for all datasets on the chart.\n
\n
```javascript\n
myBarChart.removeData();\n
// The chart will now animate and remove the first bar\n
For a radar chart, to provide context of what each point means, we include an array of strings that show around each point in the chart.\n
For the radar chart data, we have an array of datasets. Each of these is an object, with a fill colour, a stroke colour, a colour for the fill of each point, and a colour for the stroke of each point. We also have an array of data values.\n
\n
The label key on each dataset is optional, and can be used when generating a scale for the chart.\n
\n
### Chart options\n
\n
These are the customisation options specific to Radar charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.\n
\n
\n
```javascript\n
{\n
\t//Boolean - Whether to show lines for each scale point\n
\tscaleShowLine : true,\n
\n
\t//Boolean - Whether we show the angle lines out of the radar\n
\tangleShowLineOut : true,\n
\n
\t//Boolean - Whether to show labels on the scale\n
\tscaleShowLabels : false,\n
\n
\t// Boolean - Whether the scale should begin at zero\n
\tscaleBeginAtZero : true,\n
\n
\t//String - Colour of the angle line\n
\tangleLineColor : "rgba(0,0,0,.1)",\n
\n
\t//Number - Pixel width of the angle line\n
\tangleLineWidth : 1,\n
\n
\t//String - Point label font declaration\n
\tpointLabelFontFamily : "\'Arial\'",\n
\n
\t//String - Point label font weight\n
\tpointLabelFontStyle : "normal",\n
\n
\t//Number - Point label font size in pixels\n
\tpointLabelFontSize : 10,\n
\n
\t//String - Point label font colour\n
\tpointLabelFontColor : "#666",\n
\n
\t//Boolean - Whether to show a dot for each point\n
\tpointDot : true,\n
\n
\t//Number - Radius of each point dot in pixels\n
\tpointDotRadius : 3,\n
\n
\t//Number - Pixel width of point dot stroke\n
\tpointDotStrokeWidth : 1,\n
\n
\t//Number - amount extra to add to the radius to cater for hit detection outside the drawn point\n
\tpointHitDetectionRadius : 20,\n
\n
\t//Boolean - Whether to show a stroke for datasets\n
\tdatasetStroke : true,\n
\n
\t//Number - Pixel width of dataset stroke\n
\tdatasetStrokeWidth : 2,\n
\n
\t//Boolean - Whether to fill the dataset with a colour\n
\tdatasetFill : true,\n
\t{% raw %}\n
\t//String - A legend template\n
\tlegendTemplate : "<ulclass=\\"<%=name.toLowerCase()%>-legend\\"><% for (var i=0; i<datasets.length;i++){%><li><spanstyle=\\"background-color:<%=datasets[i].strokeColor%>\\"></span><%if(datasets[i].label){%><%=datasets[i].label%><%}%></li><%}%></ul>"\n
\t{% endraw %}\n
}\n
```\n
\n
\n
You can override these for your `Chart` instance by passing a second argument into the `Radar` method as an object with the keys you want to override.\n
\n
For example, we could have a radar chart without a point for each on piece of data by doing the following:\n
\n
```javascript\n
new Chart(ctx).Radar(data, {\n
\tpointDot: false\n
});\n
// This will create a chart with all of the default options, merged from the global config,\n
// and the Bar chart defaults but this particular instance will have `pointDot` set to false.\n
```\n
\n
We can also change these defaults values for each Radar type that is created, this object is available at `Chart.defaults.Radar`.\n
\n
\n
### Prototype methods\n
\n
#### .getPointsAtEvent( event )\n
\n
Calling `getPointsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event.\n
\t// => activePoints is an array of points on the canvas that are at the same position as the click event.\n
};\n
```\n
\n
This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.\n
\n
#### .update( )\n
\n
Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.\n
\n
```javascript\n
myRadarChart.datasets[0].points[2].value = 50;\n
// Would update the first dataset\'s value of \'Sleeping\' to be 50\n
myRadarChart.update();\n
// Calling update now animates the position of Sleeping from 90 to 50.\n
```\n
\n
#### .addData( valuesArray, label )\n
\n
Calling `addData(valuesArray, label)` on your Chart instance passing an array of values for each dataset, along with a label for those points.\n
\n
```javascript\n
// The values array passed into addData should be one for each dataset in the chart\n
myRadarChart.addData([40, 60], "Dancing");\n
// The new data will now animate at the end of the chart.\n
```\n
\n
#### .removeData( )\n
\n
Calling `removeData()` on your Chart instance will remove the first value for all datasets on the chart.\n
\n
```javascript\n
myRadarChart.removeData();\n
// Other points will now animate to their correct positions.\n
Polar area charts are similar to pie charts, but each segment has the same angle - the radius of the segment differs depending on the value.\n
\n
This type of chart is often useful when we want to show a comparison data similar to a pie chart, but also show a scale of values for context.\n
\n
<div class="canvas-holder">\n
\t<canvaswidth="250"height="125"></canvas>\n
</div>\n
\n
### Example usage\n
\n
```javascript\n
new Chart(ctx).PolarArea(data, options);\n
```\n
\n
### Data structure\n
\n
```javascript\n
var data = [\n
\t{\n
\t\tvalue: 300,\n
\t\tcolor:"#F7464A",\n
\t\thighlight: "#FF5A5E",\n
\t\tlabel: "Red"\n
\t},\n
\t{\n
\t\tvalue: 50,\n
\t\tcolor: "#46BFBD",\n
\t\thighlight: "#5AD3D1",\n
\t\tlabel: "Green"\n
\t},\n
\t{\n
\t\tvalue: 100,\n
\t\tcolor: "#FDB45C",\n
\t\thighlight: "#FFC870",\n
\t\tlabel: "Yellow"\n
\t},\n
\t{\n
\t\tvalue: 40,\n
\t\tcolor: "#949FB1",\n
\t\thighlight: "#A8B3C5",\n
\t\tlabel: "Grey"\n
\t},\n
\t{\n
\t\tvalue: 120,\n
\t\tcolor: "#4D5360",\n
\t\thighlight: "#616774",\n
\t\tlabel: "Dark Grey"\n
\t}\n
\n
];\n
```\n
As you can see, for the chart data you pass in an array of objects, with a value and a colour. The value attribute should be a number, while the color attribute should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL.\n
\n
### Chart options\n
\n
These are the customisation options specific to Polar Area charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.\n
\n
```javascript\n
{\n
\t//Boolean - Show a backdrop to the scale label\n
\t// Boolean - Whether the scale should begin at zero\n
\tscaleBeginAtZero : true,\n
\n
\t//Number - The backdrop padding above & below the label in pixels\n
\tscaleBackdropPaddingY : 2,\n
\n
\t//Number - The backdrop padding to the side of the label in pixels\n
\tscaleBackdropPaddingX : 2,\n
\n
\t//Boolean - Show line for each value in the scale\n
\tscaleShowLine : true,\n
\n
\t//Boolean - Stroke a line around each segment in the chart\n
\tsegmentShowStroke : true,\n
\n
\t//String - The colour of the stroke on each segment.\n
\tsegmentStrokeColor : "#fff",\n
\n
\t//Number - The width of the stroke value in pixels\n
\tsegmentStrokeWidth : 2,\n
\n
\t//Number - Amount of animation steps\n
\tanimationSteps : 100,\n
\n
\t//String - Animation easing effect.\n
\tanimationEasing : "easeOutBounce",\n
\n
\t//Boolean - Whether to animate the rotation of the chart\n
\tanimateRotate : true,\n
\n
\t//Boolean - Whether to animate scaling the chart from the centre\n
\tanimateScale : false,\n
\t{% raw %}\n
\t//String - A legend template\n
\tlegendTemplate : "<ulclass=\\"<%=name.toLowerCase()%>-legend\\"><% for (var i=0; i<segments.length;i++){%><li><spanstyle=\\"background-color:<%=segments[i].fillColor%>\\"></span><%if(segments[i].label){%><%=segments[i].label%><%}%></li><%}%></ul>"\n
\t{% endraw %}\n
}\n
```\n
\n
You can override these for your `Chart` instance by passing a second argument into the `PolarArea` method as an object with the keys you want to override.\n
\n
For example, we could have a polar area chart with a black stroke on each segment like so:\n
\n
```javascript\n
new Chart(ctx).PolarArea(data, {\n
\tsegmentStrokeColor: "#000000"\n
});\n
// This will create a chart with all of the default options, merged from the global config,\n
// and the PolarArea chart defaults but this particular instance will have `segmentStrokeColor` set to `"#000000"`.\n
```\n
\n
We can also change these defaults values for each PolarArea type that is created, this object is available at `Chart.defaults.PolarArea`.\n
\n
### Prototype methods\n
\n
#### .getSegmentsAtEvent( event )\n
\n
Calling `getSegmentsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the segment elements that are at that the same position of that event.\n
\t// => activePoints is an array of segments on the canvas that are at the same position as the click event.\n
};\n
```\n
\n
This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.\n
\n
#### .update( )\n
\n
Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.\n
\n
```javascript\n
myPolarAreaChart.segments[1].value = 10;\n
// Would update the first dataset\'s value of \'Green\' to be 10\n
myPolarAreaChart.update();\n
// Calling update now animates the position of Green from 50 to 10.\n
```\n
\n
#### .addData( segmentData, index )\n
\n
Calling `addData(segmentData, index)` on your Chart instance passing an object in the same format as in the constructor. There is an option second argument of \'index\', this determines at what index the new segment should be inserted into the chart.\n
\n
```javascript\n
// An object in the same format as the original data source\n
myPolarAreaChart.addData({\n
\tvalue: 130,\n
\tcolor: "#B48EAD",\n
\thighlight: "#C69CBE",\n
\tlabel: "Purple"\n
});\n
// The new segment will now animate in.\n
```\n
\n
#### .removeData( index )\n
\n
Calling `removeData(index)` on your Chart instance will remove segment at that particular index. If none is provided, it will default to the last segment.\n
\n
```javascript\n
myPolarAreaChart.removeData();\n
// Other segments will update to fill the empty space left.\n
Pie and doughnut charts are probably the most commonly used chart there are. They are divided into segments, the arc of each segment shows the proportional value of each piece of data.\n
\n
They are excellent at showing the relational proportions between data.\n
\n
Pie and doughnut charts are effectively the same class in Chart.js, but have one different default value - their `percentageInnerCutout`. This equates what percentage of the inner should be cut out. This defaults to `0` for pie charts, and `50` for doughnuts.\n
\n
They are also registered under two aliases in the `Chart` core. Other than their different default value, and different alias, they are exactly the same.\n
\n
<div class="canvas-holder half">\n
\t<canvaswidth="250"height="125"></canvas>\n
</div>\n
\n
<divclass="canvas-holder half">\n
\t<canvaswidth="250"height="125"></canvas>\n
</div>\n
\n
\n
### Example usage\n
\n
```javascript\n
// For a pie chart\n
var myPieChart = new Chart(ctx[0]).Pie(data,options);\n
\n
// And for a doughnut chart\n
var myDoughnutChart = new Chart(ctx[1]).Doughnut(data,options);\n
```\n
\n
### Data structure\n
\n
```javascript\n
var data = [\n
\t{\n
\t\tvalue: 300,\n
\t\tcolor:"#F7464A",\n
\t\thighlight: "#FF5A5E",\n
\t\tlabel: "Red"\n
\t},\n
\t{\n
\t\tvalue: 50,\n
\t\tcolor: "#46BFBD",\n
\t\thighlight: "#5AD3D1",\n
\t\tlabel: "Green"\n
\t},\n
\t{\n
\t\tvalue: 100,\n
\t\tcolor: "#FDB45C",\n
\t\thighlight: "#FFC870",\n
\t\tlabel: "Yellow"\n
\t}\n
]\n
```\n
\n
For a pie chart, you must pass in an array of objects with a value and an optional color property. The value attribute should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. The color attribute should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL.\n
\n
### Chart options\n
\n
These are the customisation options specific to Pie & Doughnut charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.\n
\n
```javascript\n
{\n
\t//Boolean - Whether we should show a stroke on each segment\n
\tsegmentShowStroke : true,\n
\n
\t//String - The colour of each segment stroke\n
\tsegmentStrokeColor : "#fff",\n
\n
\t//Number - The width of each segment stroke\n
\tsegmentStrokeWidth : 2,\n
\n
\t//Number - The percentage of the chart that we cut out of the middle\n
\tpercentageInnerCutout : 50, // This is 0 for Pie charts\n
\n
\t//Number - Amount of animation steps\n
\tanimationSteps : 100,\n
\n
\t//String - Animation easing effect\n
\tanimationEasing : "easeOutBounce",\n
\n
\t//Boolean - Whether we animate the rotation of the Doughnut\n
\tanimateRotate : true,\n
\n
\t//Boolean - Whether we animate scaling the Doughnut from the centre\n
\tanimateScale : false,\n
\t{% raw %}\n
\t//String - A legend template\n
\tlegendTemplate : "<ulclass=\\"<%=name.toLowerCase()%>-legend\\"><% for (var i=0; i<segments.length;i++){%><li><spanstyle=\\"background-color:<%=segments[i].fillColor%>\\"></span><%if(segments[i].label){%><%=segments[i].label%><%}%></li><%}%></ul>"\n
\t{% endraw %}\n
}\n
```\n
You can override these for your `Chart` instance by passing a second argument into the `Doughnut` method as an object with the keys you want to override.\n
\n
For example, we could have a doughnut chart that animates by scaling out from the centre like so:\n
\n
```javascript\n
new Chart(ctx).Doughnut(data, {\n
\tanimateScale: true\n
});\n
// This will create a chart with all of the default options, merged from the global config,\n
// and the Doughnut chart defaults but this particular instance will have `animateScale` set to `true`.\n
```\n
\n
We can also change these default values for each Doughnut type that is created, this object is available at `Chart.defaults.Doughnut`. Pie charts also have a clone of these defaults available to change at `Chart.defaults.Pie`, with the only difference being `percentageInnerCutout` being set to 0.\n
\n
### Prototype methods\n
\n
#### .getSegmentsAtEvent( event )\n
\n
Calling `getSegmentsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the segment elements that are at the same position of that event.\n
\t// => activePoints is an array of segments on the canvas that are at the same position as the click event.\n
};\n
```\n
\n
This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.\n
\n
#### .update( )\n
\n
Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.\n
\n
```javascript\n
myDoughnutChart.segments[1].value = 10;\n
// Would update the first dataset\'s value of \'Green\' to be 10\n
myDoughnutChart.update();\n
// Calling update now animates the circumference of the segment \'Green\' from 50 to 10.\n
// and transitions other segment widths\n
```\n
\n
#### .addData( segmentData, index )\n
\n
Calling `addData(segmentData, index)` on your Chart instance passing an object in the same format as in the constructor. There is an optional second argument of \'index\', this determines at what index the new segment should be inserted into the chart.\n
\n
```javascript\n
// An object in the same format as the original data source\n
myDoughnutChart.addData({\n
\tvalue: 130,\n
\tcolor: "#B48EAD",\n
\thighlight: "#C69CBE",\n
\tlabel: "Purple"\n
});\n
// The new segment will now animate in.\n
```\n
\n
#### .removeData( index )\n
\n
Calling `removeData(index)` on your Chart instance will remove segment at that particular index. If none is provided, it will default to the last segment.\n
\n
```javascript\n
myDoughnutChart.removeData();\n
// Other segments will update to fill the empty space left.\n
For each chart, there are a set of global prototype methods on the shared `ChartType` which you may find useful. These are available on all charts created with Chart.js, but for the examples, let\'s use a line chart we\'ve made.\n
\n
```javascript\n
// For example:\n
var myLineChart = new Chart(ctx).Line(data);\n
```\n
\n
#### .clear()\n
\n
Will clear the chart canvas. Used extensively internally between animation frames, but you might find it useful.\n
\n
```javascript\n
// Will clear the canvas that myLineChart is drawn on\n
myLineChart.clear();\n
// => returns \'this\' for chainability\n
```\n
\n
#### .stop()\n
\n
Use this to stop any current animation loop. This will pause the chart during any current animation frame. Call `.render()` to re-animate.\n
\n
```javascript\n
// Stops the charts animation loop at its current frame\n
myLineChart.stop();\n
// => returns \'this\' for chainability\n
```\n
\n
#### .resize()\n
\n
Use this to manually resize the canvas element. This is run each time the browser is resized, but you can call this method manually if you change the size of the canvas nodes container element.\n
\n
```javascript\n
// Resizes & redraws to fill its container element\n
myLineChart.resize();\n
// => returns \'this\' for chainability\n
```\n
\n
#### .destroy()\n
\n
Use this to destroy any chart instances that are created. This will clean up any references stored to the chart object within Chart.js, along with any associated event listeners attached by Chart.js.\n
\n
```javascript\n
// Destroys a specific chart instance\n
myLineChart.destroy();\n
```\n
\n
#### .toBase64Image()\n
\n
This returns a base 64 encoded string of the chart in it\'s current state.\n
\n
```javascript\n
myLineChart.toBase64Image();\n
// => returns png data url of the image on the canvas\n
```\n
\n
#### .generateLegend()\n
\n
Returns an HTML string of a legend for that chart. The template for this legend is at `legendTemplate` in the chart options.\n
\n
```javascript\n
myLineChart.generateLegend();\n
// => returns HTML string of a legend for this chart\n
```\n
\n
### External Tooltips\n
\n
You can enable custom tooltips in the global or chart configuration like so:\n
\n
```javascript\n
var myPieChart = new Chart(ctx).Pie(data, {\n
\tcustomTooltips: function(tooltip) {\n
\n
// tooltip will be false if tooltip is not visible or should be hidden\n
if (!tooltip) {\n
return;\n
}\n
\n
// Otherwise, tooltip will be an object with all tooltip properties like:\n
\n
// tooltip.caretHeight\n
// tooltip.caretPadding\n
// tooltip.chart\n
// tooltip.cornerRadius\n
// tooltip.fillColor\n
// tooltip.font...\n
// tooltip.text\n
// tooltip.x\n
// tooltip.y\n
// etc...\n
\n
};\n
});\n
```\n
\n
See files `sample/pie-customTooltips.html` and `sample/line-customTooltips.html` for examples on how to get started.\n
\n
\n
### Writing new chart types\n
\n
Chart.js 1.0 has been rewritten to provide a platform for developers to create their own custom chart types, and be able to share and utilise them through the Chart.js API.\n
\n
The format is relatively simple, there are a set of utility helper methods under `Chart.helpers`, including things such as looping over collections, requesting animation frames, and easing equations.\n
\n
On top of this, there are also some simple base classes of Chart elements, these all extend from `Chart.Element`, and include things such as points, bars and scales.\n
\n
```javascript\n
Chart.Type.extend({\n
\t// Passing in a name registers this chart in the Chart namespace\n
\tname: "Scatter",\n
\t// Providing a defaults will also register the deafults in the chart namespace\n
\tdefaults : {\n
\t\toptions: "Here",\n
\t\tavailable: "at this.options"\n
\t},\n
\t// Initialize is fired when the chart is initialized - Data is passed in as a parameter\n
\t// Config is automatically merged by the core of Chart.js, and is available at this.options\n
\tinitialize: function(data){\n
\t\tthis.chart.ctx // The drawing context for this chart\n
\t\tthis.chart.canvas // the canvas node for this chart\n
\t},\n
\t// Used to draw something on the canvas\n
\tdraw: function() {\n
\t}\n
});\n
\n
// Now we can create a new instance of our chart, using the Chart.js API\n
new Chart(ctx).Scatter(data);\n
// initialize is now run\n
```\n
\n
### Extending existing chart types\n
\n
We can also extend existing chart types, and expose them to the API in the same way. Let\'s say for example, we might want to run some more code when we initialize every Line chart.\n
\n
```javascript\n
// Notice now we\'re extending the particular Line chart type, rather than the base class.\n
Chart.types.Line.extend({\n
\t// Passing in a name registers this chart in the Chart namespace in the same way\n
// but this logs \'My Line chart extension\' in the console.\n
```\n
\n
### Community extensions\n
\n
- <ahref="https://github.com/Regaddi/Chart.StackedBar.js"target="_blank">Stacked Bar Chart</a> by <ahref="https://twitter.com/Regaddi"target="_blank">@Regaddi</a>\n
- <ahref="https://github.com/tannerlinsley/Chart.StackedArea.js"target="_blank">Stacked Bar Chart</a> by <ahref="https://twitter.com/tannerlinsley"target="_blank">@tannerlinsley</a>\n
- <ahref="https://github.com/CAYdenberg/Chart.js"target="_blank">Error bars (bar and line charts)</a> by <ahref="https://twitter.com/CAYdenberg"target="_blank">@CAYdenberg</a>\n
- <ahref="http://dima117.github.io/Chart.Scatter/"target="_blank">Scatter chart (number & date scales are supported)</a> by <ahref="https://github.com/dima117"target="_blank">@dima117</a>\n
\n
### Creating custom builds\n
\n
Chart.js uses <ahref="http://gulpjs.com/"target="_blank">gulp</a> to build the library into a single JavaScript file. We can use this same build script with custom parameters in order to build a custom version.\n
\n
Firstly, we need to ensure development dependencies are installed. With node and npm installed, after cloning the Chart.js repo to a local directory, and navigating to that directory in the command line, we can run the following:\n
\n
```bash\n
npm install\n
npm install -g gulp\n
```\n
\n
This will install the local development dependencies for Chart.js, along with a CLI for the JavaScript task runner <ahref="http://gulpjs.com/"target="_blank">gulp</a>.\n
\n
Now, we can run the `gulp build` task, and pass in a comma-separated list of types as an argument to build a custom version of Chart.js with only specified chart types.\n
\n
Here we will create a version of Chart.js with only Line, Radar and Bar charts included:\n
\n
```bash\n
gulp build --types=Line,Radar,Bar\n
```\n
\n
This will output to the `/custom` directory, and write two files, Chart.js, and Chart.min.js with only those chart types included.\n
Browser support for the canvas element is available in all modern & major mobile browsers <a href="http://caniuse.com/canvas" target="_blank">(caniuse.com/canvas)</a>.\n
\n
For IE8 & below, I would recommend using the polyfill ExplorerCanvas - available at <ahref="https://code.google.com/p/explorercanvas/"target="_blank">https://code.google.com/p/explorercanvas/</a>. It falls back to Internet explorer\'s format VML when canvas support is not available. Example use:\n
\n
```html\n
<head>\n
\t<!--[if lte IE 8]>\n
\t\t<script src="excanvas.js"></script>\n
\t<![endif]-->\n
</head>\n
```\n
\n
Usually I would recommend feature detection to choose whether or not to load a polyfill, rather than IE conditional comments, however in this case, VML is a Microsoft proprietary format, so it will only work in IE.\n
\n
Some important points to note in my experience using ExplorerCanvas as a fallback.\n
\n
- Initialise charts on load rather than DOMContentReady when using the library, as sometimes a race condition will occur, and it will result in an error when trying to get the 2d context of a canvas.\n
- New VML DOM elements are being created for each animation frame and there is no hardware acceleration. As a result animation is usually slow and jerky, with flashing text. It is a good idea to dynamically turn off animation based on canvas support. I recommend using the excellent <ahref="http://modernizr.com/"target="_blank">Modernizr</a> to do this.\n
- When declaring fonts, the library explorercanvas requires the font name to be in single quotes inside the string. For example, instead of your scaleFontFamily property being simply "Arial", explorercanvas support, use "\'Arial\'" instead. Chart.js does this for default values.\n
\n
### Bugs & issues\n
\n
Please report these on the GitHub page - at <ahref="https://github.com/nnnick/Chart.js"target="_blank">github.com/nnnick/Chart.js</a>. If you could include a link to a simple <ahref="http://jsbin.com/"target="_blank">jsbin</a> or similar to demonstrate the issue, that\'d be really helpful.\n
\n
\n
### Contributing\n
New contributions to the library are welcome, just a couple of guidelines:\n
\n
- Tabs for indentation, not spaces please.\n
- Please ensure you\'re changing the individual files in `/src`, not the concatenated output in the `Chart.js` file in the root of the repo.\n
- Please check that your code will pass `jshint` code standards, `gulp jshint` will run this for you.\n
- Please keep pull requests concise, and document new functionality in the relevant `.md` file.\n
- Consider whether your changes are useful for all users, or if creating a Chart.js extension would be more appropriate.\n
\n
### License\n
Chart.js is open source and available under the <ahref="http://opensource.org/licenses/MIT"target="_blank">MIT license</a>.
