| commit | author | age | ||
| 83c3f6 | 1 | # Doughnut and Pie |
| SP | 2 | Pie and doughnut charts are probably the most commonly used charts. They are divided into segments, the arc of each segment shows the proportional value of each piece of data. |
| 3 | ||
| 4 | They are excellent at showing the relational proportions between data. | |
| 5 | ||
| 6 | Pie and doughnut charts are effectively the same class in Chart.js, but have one different default value - their `cutoutPercentage`. This equates what percentage of the inner should be cut out. This defaults to `0` for pie charts, and `50` for doughnuts. | |
| 7 | ||
| 8 | 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. | |
| 9 | ||
| 10 | {% chartjs %} | |
| 11 | { | |
| 12 | "type": "doughnut", | |
| 13 | "data": { | |
| 14 | "labels": [ | |
| 15 | "Red", | |
| 16 | "Blue", | |
| 17 | "Yellow", | |
| 18 | ], | |
| 19 | "datasets": [{ | |
| 20 | "label": "My First Dataset", | |
| 21 | "data": [300, 50, 100], | |
| 22 | "backgroundColor": [ | |
| 23 | "rgb(255, 99, 132)", | |
| 24 | "rgb(54, 162, 235)", | |
| 25 | "rgb(255, 205, 86)", | |
| 26 | ] | |
| 27 | }] | |
| 28 | }, | |
| 29 | } | |
| 30 | {% endchartjs %} | |
| 31 | ||
| 32 | ## Example Usage | |
| 33 | ||
| 34 | ```javascript | |
| 35 | // For a pie chart | |
| 36 | var myPieChart = new Chart(ctx,{ | |
| 37 | type: 'pie', | |
| 38 | data: data, | |
| 39 | options: options | |
| 40 | }); | |
| 41 | ``` | |
| 42 | ||
| 43 | ```javascript | |
| 44 | // And for a doughnut chart | |
| 45 | var myDoughnutChart = new Chart(ctx, { | |
| 46 | type: 'doughnut', | |
| 47 | data: data, | |
| 48 | options: options | |
| 49 | }); | |
| 50 | ``` | |
| 51 | ||
| 52 | ## Dataset Properties | |
| 53 | ||
| 54 | The doughnut/pie chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a the dataset's arc are generally set this way. | |
| 55 | ||
| 56 | | Name | Type | Description | |
| 57 | | ---- | ---- | ----------- | |
| 58 | | `backgroundColor` | `Color[]` | The fill color of the arcs in the dataset. See [Colors](../general/colors.md#colors) | |
| 59 | | `borderColor` | `Color[]` | The border color of the arcs in the dataset. See [Colors](../general/colors.md#colors) | |
| 60 | | `borderWidth` | `Number[]` | The border width of the arcs in the dataset. | |
| 61 | | `hoverBackgroundColor` | `Color[]` | The fill colour of the arcs when hovered. | |
| 62 | | `hoverBorderColor` | `Color[]` | The stroke colour of the arcs when hovered. | |
| 63 | | `hoverBorderWidth` | `Number[]` | The stroke width of the arcs when hovered. | |
| 64 | ||
| 65 | ## Config Options | |
| 66 | ||
| 67 | These are the customisation options specific to Pie & Doughnut charts. These options are merged with the global chart configuration options, and form the options of the chart. | |
| 68 | ||
| 69 | | Name | Type | Default | Description | |
| 70 | | ---- | ---- | ------- | ----------- | |
| 71 | | `cutoutPercentage` | `Number` | `50` - for doughnut, `0` - for pie | The percentage of the chart that is cut out of the middle. | |
| 72 | | `rotation` | `Number` | `-0.5 * Math.PI` | Starting angle to draw arcs from. | |
| 73 | | `circumference` | `Number` | `2 * Math.PI` | Sweep to allow arcs to cover | |
| 74 | | `animation.animateRotate` | `Boolean` | `true` | If true, the chart will animate in with a rotation animation. This property is in the `options.animation` object. | |
| 75 | | `animation.animateScale` | `Boolean` | `false` | If true, will animate scaling the chart from the center outwards. | |
| 76 | ||
| 77 | ## Default Options | |
| 78 | ||
| 79 | 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 `cutoutPercentage` being set to 0. | |
| 80 | ||
| 81 | ## Data Structure | |
| 82 | ||
| 83 | For a pie chart, datasets need to contain an array of data points. The data points should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. | |
| 84 | ||
| 85 | You also need to specify an array of labels so that tooltips appear correctly | |
| 86 | ||
| 87 | ```javascript | |
| 88 | data = { | |
| 89 | datasets: [{ | |
| 90 | data: [10, 20, 30] | |
| 91 | }], | |
| 92 | ||
| 93 | // These labels appear in the legend and in the tooltips when hovering different arcs | |
| 94 | labels: [ | |
| 95 | 'Red', | |
| 96 | 'Yellow', | |
| 97 | 'Blue' | |
| 98 | ] | |
| 99 | }; | |
| 100 | ``` | |
