01-Chart-Configuration.md 20KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411
  1. ---
  2. title: Chart Configuration
  3. anchor: chart-configuration
  4. ---
  5. Chart.js provides a number of options for changing the behaviour of created charts. These configuration options can be changed on a per chart basis by passing in an options object when creating the chart. Alternatively, the global configuration can be changed which will be used by all charts created after that point.
  6. ### Creating a Chart with Options
  7. To create a chart with configuration options, simply pass an object containing your configuration to the constructor. In the example below, a line chart is created and configured to not be responsive.
  8. ```javascript
  9. var chartInstance = new Chart(ctx, {
  10. type: 'line',
  11. data: data,
  12. options: {
  13. responsive: false
  14. }
  15. });
  16. ```
  17. ### Global Configuration
  18. 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.
  19. Chart.js merges the options object passed to the chart with the global configuration using chart type defaults and scales defaults appropriately. This way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. The global general options are defined in `Chart.defaults.global`. The defaults for each chart type are discussed in the documentation for that chart type.
  20. The following example would set the hover mode to 'single' for all charts where this was not overridden by the chart type defaults or the options passed to the constructor on creation.
  21. ```javascript
  22. Chart.defaults.global.hover.mode = 'single';
  23. // Hover mode is set to single because it was not overridden here
  24. var chartInstanceHoverModeSingle = new Chart(ctx, {
  25. type: 'line',
  26. data: data,
  27. });
  28. // This chart would have the hover mode that was passed in
  29. var chartInstanceDifferentHoverMode = new Chart(ctx, {
  30. type: 'line',
  31. data: data,
  32. options: {
  33. hover: {
  34. // Overrides the global setting
  35. mode: 'label'
  36. }
  37. }
  38. })
  39. ```
  40. #### Global Font Settings
  41. There are 4 special global settings that can change all of the fonts on the chart. These options are in `Chart.defaults.global`.
  42. Name | Type | Default | Description
  43. --- | --- | --- | ---
  44. defaultFontColor | Color | '#666' | Default font color for all text
  45. defaultFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Default font family for all text
  46. defaultFontSize | Number | 12 | Default font size (in px) for text. Does not apply to radialLinear scale point labels
  47. defaultFontStyle | String | 'normal' | Default font style. Does not apply to tooltip title or footer. Does not apply to chart title
  48. ### Common Chart Configuration
  49. The following options are applicable to all charts. The can be set on the [global configuration](#chart-configuration-global-configuration), or they can be passed to the chart constructor.
  50. Name | Type | Default | Description
  51. --- | --- | --- | ---
  52. responsive | Boolean | true | Resizes when the canvas container does.
  53. responsiveAnimationDuration | Number | 0 | Duration in milliseconds it takes to animate to new size after a resize event.
  54. maintainAspectRatio | Boolean | true | Maintain the original canvas aspect ratio `(width / height)` when resizing
  55. events | Array[String] | `["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"]` | Events that the chart should listen to for tooltips and hovering
  56. onClick | Function | null | Called if the event is of type 'mouseup' or 'click'. Called in the context of the chart and passed an array of active elements
  57. legendCallback | Function | ` function (chart) { }` | Function to generate a legend. Receives the chart object to generate a legend from. Default implementation returns an HTML string.
  58. onResize | Function | null | Called when a resize occurs. Gets passed two arguemnts: the chart instance and the new size.
  59. ### Title Configuration
  60. The title configuration is passed into the `options.title` namespace. The global options for the chart title is defined in `Chart.defaults.global.title`.
  61. Name | Type | Default | Description
  62. --- | --- | --- | ---
  63. display | Boolean | false | Display the title block
  64. position | String | 'top' | Position of the title. Only 'top' or 'bottom' are currently allowed
  65. fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes)
  66. fontSize | Number | 12 | Font size inherited from global configuration
  67. fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration
  68. fontColor | Color | "#666" | Font color inherited from global configuration
  69. fontStyle | String | 'bold' | Font styling of the title.
  70. padding | Number | 10 | Number of pixels to add above and below the title text
  71. text | String | '' | Title text
  72. #### Example Usage
  73. The example below would enable a title of 'Custom Chart Title' on the chart that is created.
  74. ```javascript
  75. var chartInstance = new Chart(ctx, {
  76. type: 'line',
  77. data: data,
  78. options: {
  79. title: {
  80. display: true,
  81. text: 'Custom Chart Title'
  82. }
  83. }
  84. })
  85. ```
  86. ### Legend Configuration
  87. The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`.
  88. Name | Type | Default | Description
  89. --- | --- | --- | ---
  90. display | Boolean | true | Is the legend displayed
  91. position | String | 'top' | Position of the legend. Options are 'top' or 'bottom'
  92. fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes)
  93. onClick | Function | `function(event, legendItem) {}` | A callback that is called when a click is registered on top of a label item
  94. labels |Object|-| See the [Legend Label Configuration](#chart-configuration-legend-label-configuration) section below.
  95. #### Legend Label Configuration
  96. The legend label configuration is nested below the legend configuration using the `labels` key.
  97. Name | Type | Default | Description
  98. --- | --- | --- | ---
  99. boxWidth | Number | 40 | Width of coloured box
  100. fontSize | Number | 12 | Font size inherited from global configuration
  101. fontStyle | String | "normal" | Font style inherited from global configuration
  102. fontColor | Color | "#666" | Font color inherited from global configuration
  103. fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration
  104. padding | Number | 10 | Padding between rows of colored boxes
  105. generateLabels: | Function | `function(chart) { }` | Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See [Legend Item](#chart-configuration-legend-item-interface) for details.
  106. #### Legend Item Interface
  107. Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface.
  108. ```javascript
  109. {
  110. // Label that will be displayed
  111. text: String,
  112. // Fill style of the legend box
  113. fillStyle: Color,
  114. // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
  115. hidden: Boolean,
  116. // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
  117. lineCap: String,
  118. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
  119. lineDash: Array[Number],
  120. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
  121. lineDashOffset: Number,
  122. // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
  123. lineJoin: String,
  124. // Width of box border
  125. lineWidth: Number,
  126. // Stroke style of the legend box
  127. strokeStyle: Color
  128. }
  129. ```
  130. #### Example
  131. The following example will create a chart with the legend enabled and turn all of the text red in color.
  132. ```javascript
  133. var chartInstance = new Chart(ctx, {
  134. type: 'bar',
  135. data: data,
  136. options: {
  137. legend: {
  138. display: true,
  139. labels: {
  140. fontColor: 'rgb(255, 99, 132)'
  141. }
  142. }
  143. }
  144. });
  145. ```
  146. ### Tooltip Configuration
  147. The title configuration is passed into the `options.tooltips` namespace. The global options for the chart tooltips is defined in `Chart.defaults.global.tooltips`.
  148. Name | Type | Default | Description
  149. --- | --- | --- | ---
  150. enabled | Boolean | true | Are tooltips
  151. custom | Function | null | See [section](#chart-configuration-custom-tooltips) below
  152. mode | String | 'single' | Sets which elements appear in the tooltip. Acceptable options are `'single'` or `'label'`. `single` highlights the closest element. `label` highlights elements in all datasets at the same `X` value.
  153. itemSort | Function | undefined | Allows sorting of [tooltip items](#chart-configuration-tooltip-item-interface). Must implement a function that can be passed to [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)
  154. backgroundColor | Color | 'rgba(0,0,0,0.8)' | Background color of the tooltip
  155. titleFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip title inherited from global font family
  156. titleFontSize | Number | 12 | Font size for tooltip title inherited from global font size
  157. titleFontStyle | String | "bold" |
  158. titleFontColor | Color | "#fff" | Font color for tooltip title
  159. titleSpacing | Number | 2 | Spacing to add to top and bottom of each title line.
  160. titleMarginBottom | Number | 6 | Margin to add on bottom of title section
  161. bodyFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip items inherited from global font family
  162. bodyFontSize | Number | 12 | Font size for tooltip items inherited from global font size
  163. bodyFontStyle | String | "normal" |
  164. bodyFontColor | Color | "#fff" | Font color for tooltip items.
  165. bodySpacing | Number | 2 | Spacing to add to top and bottom of each tooltip item
  166. footerFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip footer inherited from global font family.
  167. footerFontSize | Number | 12 | Font size for tooltip footer inherited from global font size.
  168. footerFontStyle | String | "bold" | Font style for tooltip footer.
  169. footerFontColor | Color | "#fff" | Font color for tooltip footer.
  170. footerSpacing | Number | 2 | Spacing to add to top and bottom of each footer line.
  171. footerMarginTop | Number | 6 | Margin to add before drawing the footer
  172. xPadding | Number | 6 | Padding to add on left and right of tooltip
  173. yPadding | Number | 6 | Padding to add on top and bottom of tooltip
  174. caretSize | Number | 5 | Size, in px, of the tooltip arrow
  175. cornerRadius | Number | 6 | Radius of tooltip corner curves
  176. multiKeyBackground | Color | "#fff" | Color to draw behind the colored boxes when multiple items are in the tooltip
  177. callbacks | Object | | See the [callbacks section](#chart-configuration-tooltip-callbacks) below
  178. #### Tooltip Callbacks
  179. The tooltip label configuration is nested below the tooltip configuration using the `callbacks` key. The tooltip has the following callbacks for providing text. For all functions, 'this' will be the tooltip object created from the Chart.Tooltip constructor.
  180. All functions are called with the same arguments: a [tooltip item](#chart-configuration-tooltip-item-interface) and the data object passed to the chart. All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text.
  181. Callback | Arguments | Description
  182. --- | --- | ---
  183. beforeTitle | `Array[tooltipItem], data` | Text to render before the title
  184. title | `Array[tooltipItem], data` | Text to render as the title
  185. afterTitle | `Array[tooltipItem], data` | Text to render after the title
  186. beforeBody | `Array[tooltipItem], data` | Text to render before the body section
  187. beforeLabel | `tooltipItem, data` | Text to render before an individual label
  188. label | `tooltipItem, data` | Text to render for an individual item in the tooltip
  189. labelColor | `tooltipItem, chartInstace` | Returns the colors to render for the tooltip item. Return as an object containing two parameters: `borderColor` and `backgroundColor`.
  190. afterLabel | `tooltipItem, data` | Text to render after an individual label
  191. afterBody | `Array[tooltipItem], data` | Text to render after the body section
  192. beforeFooter | `Array[tooltipItem], data` | Text to render before the footer section
  193. footer | `Array[tooltipItem], data` | Text to render as the footer
  194. afterFooter | `Array[tooltipItem], data` | Text to render after the footer section
  195. #### Tooltip Item Interface
  196. The tooltip items passed to the tooltip callbacks implement the following interface.
  197. ```javascript
  198. {
  199. // X Value of the tooltip as a string
  200. xLabel: String,
  201. // Y value of the tooltip as a string
  202. yLabel: String,
  203. // Index of the dataset the item comes from
  204. datasetIndex: Number,
  205. // Index of this data item in the dataset
  206. index: Number
  207. }
  208. ```
  209. ### Hover Configuration
  210. The hover configuration is passed into the `options.hover` namespace. The global hover configuration is at `Chart.defaults.global.hover`.
  211. Name | Type | Default | Description
  212. --- | --- | --- | ---
  213. mode | String | 'single' | Sets which elements hover. Acceptable options are `'single'`, `'label'`, or `'dataset'`. `single` highlights the closest element. `label` highlights elements in all datasets at the same `X` value. `dataset` highlights the closest dataset.
  214. animationDuration | Number | 400 | Duration in milliseconds it takes to animate hover style changes
  215. onHover | Function | null | Called when any of the events fire. Called in the context of the chart and passed an array of active elements (bars, points, etc)
  216. ### Animation Configuration
  217. The following animation options are available. The global options for are defined in `Chart.defaults.global.animation`.
  218. Name | Type | Default | Description
  219. --- |:---:| --- | ---
  220. duration | Number | 1000 | The number of milliseconds an animation takes.
  221. easing | String | "easeOutQuart" | Easing function to use.
  222. onProgress | Function | none | Callback called on each step of an animation. Passed a single argument, an object, containing the chart instance and an object with details of the animation.
  223. onComplete | Function | none | Callback called at the end of an animation. Passed the same arguments as `onProgress`
  224. #### Animation Callbacks
  225. The `onProgress` and `onComplete` callbacks are useful for synchronizing an external draw to the chart animation. The callback is passed an object that implements the following interface. An example usage of these callbacks can be found on [Github](https://github.com/chartjs/Chart.js/blob/master/samples/AnimationCallbacks/progress-bar.html). This sample displays a progress bar showing how far along the animation is.
  226. ```javscript
  227. {
  228. // Chart object
  229. chartInstance,
  230. // Contains details of the on-going animation
  231. animationObject,
  232. }
  233. ```
  234. #### Animation Object
  235. The animation object passed to the callbacks is of type `Chart.Animation`. The object has the following parameters.
  236. ```javascript
  237. {
  238. // Current Animation frame number
  239. currentStep: Number,
  240. // Number of animation frames
  241. numSteps: Number,
  242. // Animation easing to use
  243. easing: String,
  244. // Function that renders the chart
  245. render: Function,
  246. // User callback
  247. onAnimationProgress: Function,
  248. // User callback
  249. onAnimationComplete: Function
  250. }
  251. ```
  252. ### Element Configuration
  253. The global options for elements are defined in `Chart.defaults.global.elements`.
  254. Options can be configured for four different types of elements; arc, lines, points, and rectangles. When set, these options apply to all objects of that type unless specifically overridden by the configuration attached to a dataset.
  255. #### Arc Configuration
  256. Arcs are used in the polar area, doughnut and pie charts. They can be configured with the following options. The global arc options are stored in `Chart.defaults.global.elements.arc`.
  257. Name | Type | Default | Description
  258. --- | --- | --- | ---
  259. backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default fill color for arcs. Inherited from the global default
  260. borderColor | Color | '#fff' | Default stroke color for arcs
  261. borderWidth | Number | 2 | Default stroke width for arcs
  262. #### Line Configuration
  263. Line elements are used to represent the line in a line chart. The global line options are stored in `Chart.defaults.global.elements.line`.
  264. Name | Type | Default | Description
  265. --- | --- | --- | ---
  266. tension | Number | 0.4 | Default bezier curve tension. Set to `0` for no bezier curves.
  267. backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default line fill color
  268. borderWidth | Number | 3 | Default line stroke width
  269. borderColor | Color | 'rgba(0,0,0,0.1)' | Default line stroke color
  270. borderCapStyle | String | 'butt' | Default line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap)
  271. borderDash | Array | `[]` | Default line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash)
  272. borderDashOffset | Number | 0.0 | Default line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset)
  273. borderJoinStyle | String | 'miter' | Default line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin)
  274. fill | Boolean | true | If true, the line is filled.
  275. #### Point Configuration
  276. Point elements are used to represent the points in a line chart or a bubble chart. The global point options are stored in `Chart.defaults.global.elements.point`.
  277. Name | Type | Default | Description
  278. --- | --- | --- | ---
  279. radius | Number | 3 | Default point radius
  280. pointStyle | String | 'circle' | Default point style
  281. backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default point fill color
  282. borderWidth | Number | 1 | Default point stroke width
  283. borderColor | Color | 'rgba(0,0,0,0.1)' | Default point stroke color
  284. hitRadius | Number | 1 | Extra radius added to point radius for hit detection
  285. hoverRadius | Number | 4 | Default point radius when hovered
  286. hoverBorderWidth | Number | 1 | Default stroke width when hovered
  287. #### Rectangle Configuration
  288. Rectangle elements are used to represent the bars in a bar chart. The global rectangle options are stored in `Chart.defaults.global.elements.rectange`.
  289. Name | Type | Default | Description
  290. --- | --- | --- | ---
  291. backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default bar fill color
  292. borderWidth | Number | 0 | Default bar stroke width
  293. borderColor | Color | 'rgba(0,0,0,0.1)' | Default bar stroke color
  294. borderSkipped | String | 'bottom' | Default skipped (excluded) border for rectangle. Can be one of `bottom`, `left`, `top`, `right`
  295. ### Colors
  296. When supplying colors to Chart options, you can use a number of formats. You can specify the color as a string in hexadecimal, RGB, or HSL notations. If a color is needed, but not specified, Chart.js will use the global default color. This color is stored at `Chart.defaults.global.defaultColor`. It is initially set to 'rgb(0, 0, 0, 0.1)';
  297. You can also pass a [CanvasGradient](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient) object. You will need to create this before passing to the chart, but using it you can achieve some interesting effects.
  298. The final option is to pass a [CanvasPattern](https://developer.mozilla.org/en-US/docs/Web/API/CanvasPattern) object. For example, if you wanted to fill a dataset with a pattern from an image you could do the following.
  299. ```javascript
  300. var img = new Image();
  301. img.src = 'https://example.com/my_image.png';
  302. img.onload = function() {
  303. var ctx = document.getElementById('canvas').getContext('2d');
  304. var fillPattern = ctx.createPattern(img, 'repeat');
  305. var chart = new Chart(ctx, {
  306. data: {
  307. labels: ['Item 1', 'Item 2', 'Item 3'],
  308. datasets: [{
  309. data: [10, 20, 30],
  310. backgroundColor: fillPattern
  311. }]
  312. }
  313. })
  314. }
  315. ```