diff --git a/docs/00-Getting-Started.md b/docs/00-Getting-Started.md index 37d9bad6d..2a11f9bff 100644 --- a/docs/00-Getting-Started.md +++ b/docs/00-Getting-Started.md @@ -118,181 +118,3 @@ var myChart = new Chart(ctx, { ``` It's that easy to get started using Chart.js! From here you can explore the many options that can help you customise your charts with scales, tooltips, labels, colors, custom actions, and much more. - -### Global chart configuration - -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. - -Chart.js merges configurations and options in a few places with the global defaults using chart type defaults and scales defaults. This way you can be as specific as you want in your individual chart configs, or change the defaults for Chart.js as a whole. - -The global options are defined in `Chart.defaults.global`. - -Name | Type | Default | Description ---- | --- | --- | --- -responsive | Boolean | true | Resizes when the canvas container does. -responsiveAnimationDuration | Number | 0 | Duration in milliseconds it takes to animate to new size after a resize event. -maintainAspectRatio | Boolean | true | Maintain the original canvas aspect ratio `(width / height)` when resizing -events | Array[String] | `["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"]` | Events that the chart should listen to for tooltips and hovering -hover |Object|-|- -*hover*.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) -*hover*.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. -*hover*.animationDuration | Number | 400 | Duration in milliseconds it takes to animate hover style changes -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 -defaultColor | Color | 'rgba(0,0,0,0.1)' | -defaultFontColor | Color | '#666' | Default font color for all text -defaultFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Default font family for all text -defaultFontSize | Number | 12 | Default font size (in px) for text. Does not apply to radialLinear scale point labels -defaultFontStyle | String | 'normal' | Default font style. Does not apply to tooltip title or footer. Does not apply to chart title -legendCallback | Function | ` function (chart) { }` | Function to generate a legend. Receives the chart object to generate a legend from. Default implementation returns an HTML string. - -The global options for the chart title is defined in `Chart.defaults.global.title` - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | false | Show the title block -position | String | 'top' | Position of the title. 'top' or 'bottom' are allowed -fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) -fontColor | Color | '#666' | Text color -fontFamily | String | 'Helvetica Neue' | -fontSize | Number | 12 | -fontStyle | String | 'bold' | -padding | Number | 10 | Number of pixels to add above and below the title text -text | String | '' | Title text - -The global options for the chart legend is defined in `Chart.defaults.global.legend` - -Name | Type | Default | Description ---- | --- | --- | --- -display | Boolean | true | Is the legend displayed -position | String | 'top' | Position of the legend. Options are 'top' or 'bottom' -fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) -onClick | Function | `function(event, legendItem) {}` | A callback that is called when a click is registered on top of a label item -labels |Object|-|- -*labels*.boxWidth | Number | 40 | Width of coloured box -*labels*.fontSize | Number | 12 | Font size -*labels*.fontStyle | String | "normal" | -*labels*.fontColor | Color | "#666" | -*labels*.fontFamily | String | "Helvetica Neue" | -*labels*.padding | Number | 10 | Padding between rows of colored boxes -*labels*.generateLabels: | Function | `function(chart) { }` | Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. Styles that can be returned are `fillStyle`, `strokeStyle`, `lineCap`, `lineDash`, `lineDashOffset`, `lineWidth`, `lineJoin`. Return a `hidden` attribute to indicate that the label refers to something that is not visible. A strikethrough style will be given to the text in this case. - -The global options for tooltips are defined in `Chart.defaults.global.tooltips`. - -Name | Type | Default | Description ---- |:---:| --- | --- -enabled | Boolean | true | -custom | | null | -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. -backgroundColor | Color | 'rgba(0,0,0,0.8)' | Background color of the tooltip - | | | -Label | | | There are three labels you can control. `title`, `body`, `footer` the star (\*) represents one of these three. *(i.e. titleFontFamily, footerSpacing)* -\*FontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | -\*FontSize | Number | 12 | -\*FontStyle | String | title - "bold", body - "normal", footer - "bold" | -\*Spacing | Number | 2 | -\*Color | Color | "#fff" | -\*Align | String | "left" | text alignment. See [MDN Canvas Documentation](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign) -titleMarginBottom | Number | 6 | Margin to add on bottom of title section -footerMarginTop | Number | 6 | Margin to add before drawing the footer -xPadding | Number | 6 | Padding to add on left and right of tooltip -yPadding | Number | 6 | Padding to add on top and bottom of tooltip -caretSize | Number | 5 | Size, in px, of the tooltip arrow -cornerRadius | Number | 6 | Radius of tooltip corner curves -multiKeyBackground | Color | "#fff" | Color to draw behind the colored boxes when multiple items are in the tooltip - | | | -callbacks | Object | - | V2.0 introduces callback functions as a replacement for the template engine in v1. The tooltip has the following callbacks for providing text. For all functions, 'this' will be the tooltip object create from the Chart.Tooltip constructor -**Callback Functions** | | | All functions are called with the same arguments -xLabel | String or Array[Strings] | | This is the xDataValue for each item to be displayed in the tooltip -yLabel | String or Array[Strings] | | This is the yDataValue for each item to be displayed in the tooltip -index | Number | | Data index. -data | Object | | Data object passed to chart. -`return`| String or Array[Strings] | | All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text. - | | | -*callbacks*.beforeTitle | Function | none | Text to render before the title -*callbacks*.title | Function | `function(tooltipItems, data) { //Pick first xLabel }` | Text to render as the title -*callbacks*.afterTitle | Function | none | Text to render after the ttiel -*callbacks*.beforeBody | Function | none | Text to render before the body section -*callbacks*.beforeLabel | Function | none | Text to render before an individual label -*callbacks*.label | Function | `function(tooltipItem, data) { // Returns "datasetLabel: tooltipItem.yLabel" }` | Text to render as label -*callbacks*.afterLabel | Function | none | Text to render after an individual label -*callbacks*.afterBody | Function | none | Text to render after the body section -*callbacks*.beforeFooter | Function | none | Text to render before the footer section -*callbacks*.footer | Function | none | Text to render as the footer -*callbacks*.afterFooter | Function | none | Text to render after the footer section - -The global options for animations are defined in `Chart.defaults.global.animation`. - -Name | Type | Default | Description ---- |:---:| --- | --- -duration | Number | 1000 | The number of milliseconds an animation takes. -easing | String | "easeOutQuart" | Easing function to use. -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. -onComplete | Function | none | Callback called at the end of an animation. Passed the same arguments as `onProgress` - -The global options for elements are defined in `Chart.defaults.global.elements`. - -Name | Type | Default | Description ---- |:---:| --- | --- -arc | Object | - | - -*arc*.backgroundColor | Color | `Chart.defaults.global.defaultColor` | Default fill color for arcs -*arc*.borderColor | Color | "#fff" | Default stroke color for arcs -*arc*.borderWidth | Number | 2 | Default stroke width for arcs -line | Object | - | - -*line*.tension | Number | 0.4 | Default bezier curve tension. Set to `0` for no bezier curves. -*line*.backgroundColor | Color | `Chart.defaults.global.defaultColor` | Default line fill color -*line*.borderWidth | Number | 3 | Default line stroke width -*line*.borderColor | Color | `Chart.defaults.global.defaultColor` | Default line stroke color -*line*.borderCapStyle | String | 'butt' | Default line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap) -*line*.borderDash | Array | `[]` | Default line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) -*line*.borderDashOffset | Number | 0.0 | Default line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) -*line*.borderJoinStyle | String | 'miter' | Default line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -*line*.fill | Boolean | true | -point | Object | - | - -*point*.radius | Number | 3 | Default point radius -*point*.pointStyle | String | 'circle' | Default point style -*point*.backgroundColor | Color | `Chart.defaults.global.defaultColor` | Default point fill color -*point*.borderWidth | Number | 1 | Default point stroke width -*point*.borderColor | Color | `Chart.defaults.global.defaultColor` | Default point stroke color -*point*.hitRadius | Number | 1 | Extra radius added to point radius for hit detection -*point*.hoverRadius | Number | 4 | Default point radius when hovered -*point*.hoverBorderWidth | Number | 1 | Default stroke width when hovered -rectangle | Object | - | - -*rectangle*.backgroundColor | Color | `Chart.defaults.global.defaultColor` | Default bar fill color -*rectangle*.borderWidth | Number | 0 | Default bar stroke width -*rectangle*.borderColor | Color | `Chart.defaults.global.defaultColor` | Default bar stroke color -*rectangle*.borderSkipped | String | 'bottom' | Default skipped (excluded) border for rectangle. Can be one of `bottom`, `left`, `top`, `right` - -If for example, you wanted all charts created to be responsive, and resize when the browser window does, the following setting can be changed: - -```javascript -Chart.defaults.global.responsive = true; -``` - -Now, every time we create a chart, `options.responsive` will be `true`. - -### Colors -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. - -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. - -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. - -```javascript -var img = new Image(); -img.src = 'https://example.com/my_image.png'; -img.onload = function() { - var ctx = document.getElementById('canvas').getContext('2d'); - var fillPattern = ctx.createPattern(img, 'repeat'); - - var chart = new Chart(ctx, { - data: { - labels: ['Item 1', 'Item 2', 'Item 3'], - datasets: [{ - data: [10, 20, 30], - backgroundColor: fillPattern - }] - } - }) -} - -``` diff --git a/docs/01-Chart-Configuration.md b/docs/01-Chart-Configuration.md new file mode 100644 index 000000000..80e079f6d --- /dev/null +++ b/docs/01-Chart-Configuration.md @@ -0,0 +1,408 @@ +--- +title: Chart Configuration +anchor: chart-configuration +--- + +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. + +### Creating a Chart with Options + +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. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + responsive: false + } +}); +``` + +### Global Configuration + +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. + +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. + +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. + +```javascript +Chart.defaults.global.hover.mode = 'single'; + +// Hover mode is set to single because it was not overridden here +var chartInstanceHoverModeSingle = new Chart(ctx, { + type: 'line', + data: data, +}); + +// This chart would have the hover mode that was passed in +var chartInstanceDifferentHoverMode = new Chart(ctx, { + type: 'line', + data: data, + options: { + hover: { + // Overrides the global setting + mode: 'label' + } + } +}) +``` + +#### Global Font Settings + +There are 4 special global settings that can change all of the fonts on the chart. These options are in `Chart.defaults.global`. + +Name | Type | Default | Description +--- | --- | --- | --- +defaultFontColor | Color | '#666' | Default font color for all text +defaultFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Default font family for all text +defaultFontSize | Number | 12 | Default font size (in px) for text. Does not apply to radialLinear scale point labels +defaultFontStyle | String | 'normal' | Default font style. Does not apply to tooltip title or footer. Does not apply to chart title + +### Common Chart Configuration + +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. + +Name | Type | Default | Description +--- | --- | --- | --- +responsive | Boolean | true | Resizes when the canvas container does. +responsiveAnimationDuration | Number | 0 | Duration in milliseconds it takes to animate to new size after a resize event. +maintainAspectRatio | Boolean | true | Maintain the original canvas aspect ratio `(width / height)` when resizing +events | Array[String] | `["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"]` | Events that the chart should listen to for tooltips and hovering +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 +legendCallback | Function | ` function (chart) { }` | Function to generate a legend. Receives the chart object to generate a legend from. Default implementation returns an HTML string. + +### Title Configuration + +The title configuration is passed into the `options.title` namespace. The global options for the chart title is defined in `Chart.defaults.global.title`. + +Name | Type | Default | Description +--- | --- | --- | --- +display | Boolean | false | Display the title block +position | String | 'top' | Position of the title. Only 'top' or 'bottom' are currently allowed +fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) +fontSize | Number | 12 | Font size inherited from global configuration +fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration +fontColor | Color | "#666" | Font color inherited from global configuration +fontStyle | String | 'bold' | Font styling of the title. +padding | Number | 10 | Number of pixels to add above and below the title text +text | String | '' | Title text + +#### Example Usage + +The example below would enable a title of 'Custom Chart Title' on the chart that is created. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + title: { + display: true, + text: 'Custom Chart Title' + } + } +}) +``` + +### Legend Configuration + +The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`. + +Name | Type | Default | Description +--- | --- | --- | --- +display | Boolean | true | Is the legend displayed +position | String | 'top' | Position of the legend. Options are 'top' or 'bottom' +fullWidth | Boolean | true | Marks that this box should take the full width of the canvas (pushing down other boxes) +onClick | Function | `function(event, legendItem) {}` | A callback that is called when a click is registered on top of a label item +labels |Object|-| See the [Legend Label Configuration](#chart-configuration-legend-label-configuration) section below. + +#### Legend Label Configuration + +The legend label configuration is nested below the legend configuration using the `labels` key. + +Name | Type | Default | Description +--- | --- | --- | --- +boxWidth | Number | 40 | Width of coloured box +fontSize | Number | 12 | Font size inherited from global configuration +fontStyle | String | "normal" | Font style inherited from global configuration +fontColor | Color | "#666" | Font color inherited from global configuration +fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family inherited from global configuration +padding | Number | 10 | Padding between rows of colored boxes +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. + +#### Legend Item Interface + +Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface. + +```javascript +{ + // Label that will be displayed + text: String, + + // Fill style of the legend box + fillStyle: Color, + + // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect + hidden: Boolean, + + // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap + lineCap: String, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash + lineDash: Array[Number], + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset + lineDashOffset: Number, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin + lineJoin: String, + + // Width of box border + lineWidth: Number, + + // Stroke style of the legend box + strokeStyle: Color +} +``` + +#### Example + +The following example will create a chart with the legend enabled and turn all of the text red in color. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'bar', + data: data, + options: { + legend: { + display: true, + labels: { + fontColor: 'rgb(255, 99, 132)' + } + } + } +}); +``` + +### Tooltip Configuration + +The title configuration is passed into the `options.tooltips` namespace. The global options for the chart tooltips is defined in `Chart.defaults.global.title`. + +Name | Type | Default | Description +--- | --- | --- | --- +enabled | Boolean | true | Are tooltips +custom | Function | null | See [section](#chart-configuration-custom-tooltips) below +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. +backgroundColor | Color | 'rgba(0,0,0,0.8)' | Background color of the tooltip +titleFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip title inherited from global font family +titleFontSize | Number | 12 | Font size for tooltip title inherited from global font size +titleFontStyle | String | "bold" | +titleFontColor | Color | "#fff" | Font color for tooltip title +titleSpacing | Number | 2 | Spacing to add to top and bottom of each title line. +titleMarginBottom | Number | 6 | Margin to add on bottom of title section +bodyFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip items inherited from global font family +bodyFontSize | Number | 12 | Font size for tooltip items inherited from global font size +bodyFontStyle | String | "normal" | +bodyFontColor | Color | "#fff" | Font color for tooltip items. +bodySpacing | Number | 2 | Spacing to add to top and bottom of each tooltip item +footerFontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for tooltip footer inherited from global font family. +footerFontSize | Number | 12 | Font size for tooltip footer inherited from global font size. +footerFontStyle | String | "bold" | Font style for tooltip footer. +footerFontColor | Color | "#fff" | Font color for tooltip footer. +footerSpacing | Number | 2 | Spacing to add to top and bottom of each footer line. +footerMarginTop | Number | 6 | Margin to add before drawing the footer +xPadding | Number | 6 | Padding to add on left and right of tooltip +yPadding | Number | 6 | Padding to add on top and bottom of tooltip +caretSize | Number | 5 | Size, in px, of the tooltip arrow +cornerRadius | Number | 6 | Radius of tooltip corner curves +multiKeyBackground | Color | "#fff" | Color to draw behind the colored boxes when multiple items are in the tooltip +callbacks | Object | | See the [callbacks section](#chart-configuration-tooltip-callbacks) below + +#### Tooltip Callbacks + +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. + +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. + +Callback | Arguments | Description +--- | --- | --- +beforeTitle | `Array[tooltipItem], data` | Text to render before the title +title | `Array[tooltipItem], data` | Text to render as the title +afterTitle | `Array[tooltipItem], data` | Text to render after the title +beforeBody | `Array[tooltipItem], data` | Text to render before the body section +beforeLabel | `tooltipItem, data` | Text to render before an individual label +label | `tooltipItem, data` | Text to render for an individual item in the tooltip +afterLabel | `tooltipItem, data` | Text to render after an individual label +afterBody | `Array[tooltipItem], data` | Text to render after the body section +beforeFooter | `Array[tooltipItem], data` | Text to render before the footer section +footer | `Array[tooltipItem], data` | Text to render as the footer +afterFooter | `Array[tooltipItem], data` | Text to render after the footer section + +#### Tooltip Item Interface + +The tooltip items passed to the tooltip callbacks implement the following interface. + +```javascript +{ + // X Value of the tooltip as a string + xLabel: String, + + // Y value of the tooltip as a string + yLabel: String, + + // Index of the dataset the item comes from + datasetIndex: Number, + + // Index of this data item in the dataset + index: Number +} +``` + +### Hover Configuration + +The hover configuration is passed into the `options.hover` namespace. The global hover configuration is at `Chart.defaults.global.hover`. + +Name | Type | Default | Description +--- | --- | --- | --- +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. +animationDuration | Number | 400 | Duration in milliseconds it takes to animate hover style changes +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) + +### Animation Configuration + +The following animation options are available. The global options for are defined in `Chart.defaults.global.animation`. + +Name | Type | Default | Description +--- |:---:| --- | --- +duration | Number | 1000 | The number of milliseconds an animation takes. +easing | String | "easeOutQuart" | Easing function to use. +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. +onComplete | Function | none | Callback called at the end of an animation. Passed the same arguments as `onProgress` + +#### Animation Callbacks + +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. + +```javscript +{ + // Chart object + chartInstance, + + // Contains details of the on-going animation + animationObject, +} +``` + +#### Animation Object + +The animation object passed to the callbacks is of type `Chart.Animation`. The object has the following parameters. + +```javascript +{ + // Current Animation frame number + currentStep: Number, + + // Number of animation frames + numSteps: Number, + + // Animation easing to use + easing: String, + + // Function that renders the chart + render: Function, + + // User callback + onAnimationProgress: Function, + + // User callback + onAnimationComplete: Function +} +``` + +### Element Configuration + +The global options for elements are defined in `Chart.defaults.global.elements`. + +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. + +#### Arc Configuration + +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`. + +Name | Type | Default | Description +--- | --- | --- | --- +backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default fill color for arcs. Inherited from the global default +borderColor | Color | '#fff' | Default stroke color for arcs +borderWidth | Number | 2 | Default stroke width for arcs + +#### Line Configuration + +Line elements are used to represent the line in a line chart. The global line options are stored in `Chart.defaults.global.elements.line`. + +Name | Type | Default | Description +--- | --- | --- | --- +tension | Number | 0.4 | Default bezier curve tension. Set to `0` for no bezier curves. +backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default line fill color +borderWidth | Number | 3 | Default line stroke width +borderColor | Color | 'rgba(0,0,0,0.1)' | Default line stroke color +borderCapStyle | String | 'butt' | Default line cap style. See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap) +borderDash | Array | `[]` | Default line dash. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) +borderDashOffset | Number | 0.0 | Default line dash offset. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) +borderJoinStyle | String | 'miter' | Default line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) +fill | Boolean | true | If true, the line is filled. + +#### Point Configuration + +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`. + +Name | Type | Default | Description +--- | --- | --- | --- +radius | Number | 3 | Default point radius +pointStyle | String | 'circle' | Default point style +backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default point fill color +borderWidth | Number | 1 | Default point stroke width +borderColor | Color | 'rgba(0,0,0,0.1)' | Default point stroke color +hitRadius | Number | 1 | Extra radius added to point radius for hit detection +hoverRadius | Number | 4 | Default point radius when hovered +hoverBorderWidth | Number | 1 | Default stroke width when hovered + +#### Rectangle Configuration + +Rectangle elements are used to represent the bars in a bar chart. The global rectangle options are stored in `Chart.defaults.global.elements.rectange`. + +Name | Type | Default | Description +--- | --- | --- | --- +backgroundColor | Color | 'rgba(0,0,0,0.1)' | Default bar fill color +borderWidth | Number | 0 | Default bar stroke width +borderColor | Color | 'rgba(0,0,0,0.1)' | Default bar stroke color +borderSkipped | String | 'bottom' | Default skipped (excluded) border for rectangle. Can be one of `bottom`, `left`, `top`, `right` + +### Colors + +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)'; + +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. + +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. + +```javascript +var img = new Image(); +img.src = 'https://example.com/my_image.png'; +img.onload = function() { + var ctx = document.getElementById('canvas').getContext('2d'); + var fillPattern = ctx.createPattern(img, 'repeat'); + + var chart = new Chart(ctx, { + data: { + labels: ['Item 1', 'Item 2', 'Item 3'], + datasets: [{ + data: [10, 20, 30], + backgroundColor: fillPattern + }] + } + }) +} + +``` \ No newline at end of file diff --git a/docs/01-Scales.md b/docs/01-Scales.md deleted file mode 100644 index c7b2742bb..000000000 --- a/docs/01-Scales.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: Scales -anchor: scales ---- - -Scales in v2.0 of Chart.js are significantly more powerful, but also different than those of v1.0. -* Multiple x & y axes are now supported. -* A built-in label auto-skip feature now detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally. -* Scale titles are now supported -* New scale types can be extended without writing an entirely new chart type - -Every scale extends a core scale class with the following options: - -Name | Type | Default | Description ---- |:---:| --- | --- -type | String | Chart specific. | Type of scale being employed. Custom scales can be created and registered with a string key. Options: ["category"](#scales-category-scale), ["linear"](#scales-linear-scale), ["logarithmic"](#scales-logarithmic-scale), ["time"](#scales-time-scale), ["radialLinear"](#scales-radial-linear-scale) -display | Boolean | true | If true, show the scale including gridlines, ticks, and labels. Overrides *gridLines.display*, *scaleLabel.display*, and *ticks.display*. -position | String | "left" | Position of the scale. Possible values are top, left, bottom and right. -beforeUpdate | Function | undefined | Callback called before the update process starts. Passed a single argument, the scale instance. -beforeSetDimensions | Function | undefined | Callback that runs before dimensions are set. Passed a single argument, the scale instance. -afterSetDimensions | Function | undefined | Callback that runs after dimensions are set. Passed a single argument, the scale instance. -beforeDataLimits | Function | undefined | Callback that runs before data limits are determined. Passed a single argument, the scale instance. -afterDataLimits | Function | undefined | Callback that runs after data limits are determined. Passed a single argument, the scale instance. -beforeBuildTicks | Function | undefined | Callback that runs before ticks are created. Passed a single argument, the scale instance. -afterBuildTicks | Function | undefined | Callback that runs after ticks are created. Useful for filtering ticks. Passed a single argument, the scale instance. -beforeTickToLabelConversion | Function | undefined | Callback that runs before ticks are converted into strings. Passed a single argument, the scale instance. -afterTickToLabelConversion | Function | undefined | Callback that runs after ticks are converted into strings. Passed a single argument, the scale instance. -beforeCalculateTickRotation | Function | undefined | Callback that runs before tick rotation is determined. Passed a single argument, the scale instance. -afterCalculateTickRotation | Function | undefined | Callback that runs after tick rotation is determined. Passed a single argument, the scale instance. -beforeFit | Function | undefined | Callback that runs before the scale fits to the canvas. Passed a single argument, the scale instance. -afterFit | Function | undefined | Callback that runs after the scale fits to the canvas. Passed a single argument, the scale instance. -afterUpdate | Function | undefined | Callback that runs at the end of the update process. Passed a single argument, the scale instance. -**gridLines** | Object | - | Options for the grid lines that run perpendicular to the axis. -*gridLines*.display | Boolean | true | -*gridLines*.color | Color | "rgba(0, 0, 0, 0.1)" | Color of the grid lines. -*gridLines*.lineWidth | Number | 1 | Stroke width of grid lines -*gridLines*.drawBorder | Boolean | true | If true draw border on the edge of the chart -*gridLines*.drawOnChartArea | Boolean | true | If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn -*gridLines*.drawTicks | Boolean | true | If true, draw lines beside the ticks in the axis area beside the chart. -*gridLines*.tickMarkLength | Number | 10 | Length in pixels that the grid lines will draw into the axis area. -*gridLines*.zeroLineWidth | Number | 1 | Stroke width of the grid line for the first index (index 0). -*gridLines*.zeroLineColor | Color | "rgba(0, 0, 0, 0.25)" | Stroke color of the grid line for the first index (index 0). -*gridLines*.offsetGridLines | Boolean | false | If true, offset labels from grid lines. -**scaleLabel** | Object | | Title for the entire axis. -*scaleLabel*.display | Boolean | false | -*scaleLabel*.labelString | String | "" | The text for the title. (i.e. "# of People", "Response Choices") -*scaleLabel*.fontColor | Color | "#666" | Font color for the scale title. -*scaleLabel*.fontFamily| String | "Helvetica Neue" | Font family for the scale title, follows CSS font-family options. -*scaleLabel*.fontSize | Number | 12 | Font size for the scale title. -*scaleLabel*.fontStyle | String | "normal" | Font style for the scale title, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). -**ticks** | Object | | Settings for the labels that run along the axis. -*ticks*.beginAtZero | Boolean | false | If true the scale will be begin at 0, if false the ticks will begin at your smallest data value. -*ticks*.fontColor | Color | "#666" | Font color for the tick labels. -*ticks*.fontFamily | String | "Helvetica Neue" | Font family for the tick labels, follows CSS font-family options. -*ticks*.fontSize | Number | 12 | Font size for the tick labels. -*ticks*.fontStyle | String | "normal" | Font style for the tick labels, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). -*ticks*.minRotation | Number | 0 | Minimum rotation for tick labels -*ticks*.maxRotation | Number | 90 | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* -*ticks*.minRotation | Number | 20 | *currently not-implemented* Minimum rotation for tick labels when condensing is necessary. *Note: Only applicable to horizontal scales.* -*ticks*.maxTicksLimit | Number | 11 | Maximum number of ticks and gridlines to show. If not defined, it will limit to 11 ticks but will show all gridlines. -*ticks*.padding | Number | 10 | Padding between the tick label and the axis. *Note: Only applicable to horizontal scales.* -*ticks*.labelOffset | Number | 0 | Distance in pixels to offset the label from the centre point of the tick (in the y direction for the x axis, and the x direction for the y axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* -*ticks*.mirror | Boolean | false | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* -*ticks*.reverse | Boolean | false | Reverses order of tick labels. -*ticks*.display | Boolean | true | If true, show the ticks. -*ticks*.suggestedMin | Number | - | User defined minimum number for the scale, overrides minimum value *except for if* it is higher than the minimum value. -*ticks*.suggestedMax | Number | - | User defined maximum number for the scale, overrides maximum value *except for if* it is lower than the maximum value. -*ticks*.min | Number | - | User defined minimum number for the scale, overrides minimum value. -*ticks*.max | Number | - | User defined maximum number for the scale, overrides maximum value -*ticks*.autoSkip | Boolean | true | If true, automatically calculates how many labels that can be shown and hides labels accordingly. Turn it off to show all labels no matter what -*ticks*.callback | Function | `function(value) { return '' + value; } ` | Returns the string representation of the tick value as it should be displayed on the chart. - -The `callback` method may be used for advanced tick customization. The following callback would display every label in scientific notation -```javascript -{ - scales: { - xAxes: [{ - ticks: { - // Return an empty string to draw the tick line but hide the tick label - // Return `null` or `undefined` to hide the tick line entirely - userCallback: function(value, index, values) { - return value.toExponential(); - } - } - }] - } -} -``` - -### Category Scale -The category scale will be familiar to those who have used v1.0. Labels are drawn in from the labels array included in the chart data. - -The category scale extends the core scale class with the following tick template: - -```javascript -{ - position: "bottom", -} -``` - -The `ticks.min` and `ticks.max` attributes may be used with the category scale. Unlike other scales, the value of these attributes must simply be something that can be found in the `labels` array of the data object. - -### Linear Scale -The linear scale can be used to display numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to use one of these scales for the x axis. - -The linear scale extends the core scale class with the following tick template: - -```javascript -{ - position: "left", - ticks: { - callback: function(tickValue, index, ticks) { - var delta = ticks[1] - ticks[0]; - - // If we have a number like 2.5 as the delta, figure out how many decimal places we need - if (Math.abs(delta) > 1) { - if (tickValue !== Math.floor(tickValue)) { - // not an integer - delta = tickValue - Math.floor(tickValue); - } - } - - var logDelta = helpers.log10(Math.abs(delta)); - var tickString = ''; - - if (tickValue !== 0) { - var numDecimal = -1 * Math.floor(logDelta); - numDecimal = Math.max(Math.min(numDecimal, 20), 0); // toFixed has a max of 20 decimal places - tickString = tickValue.toFixed(numDecimal); - } else { - tickString = '0'; // never show decimal places for 0 - } - - return tickString; - } - } -} -``` - -It also provides additional configuration options: - -Name | Type | Default | Description ---- |:---:| --- | --- -*ticks*.stepSize | Number | - | User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. - -### Logarithmic Scale -The logarithmic scale is used to display logarithmic data of course. It can be placed on either the x or y axis. - -The log scale extends the core scale class with the following tick template: - -```javascript -{ - position: "left", - ticks: { - callback: function(value) { - var remain = value / (Math.pow(10, Math.floor(Chart.helpers.log10(value)))); - - if (remain === 1 || remain === 2 || remain === 5) { - return value.toExponential(); - } else { - return ''; - } - } - } -} -``` - -### Time Scale -The time scale is used to display times and dates. It can be placed on the x axis. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. - -The time scale extends the core scale class with the following tick template: - -```javascript -{ - position: "bottom", - time: { - // string/callback - By default, date objects are expected. You may use a pattern string from http://momentjs.com/docs/#/parsing/string-format/ to parse a time string format, or use a callback function that is passed the label, and must return a moment() instance. - parser: false, - // string - By default, unit will automatically be detected. Override with 'week', 'month', 'year', etc. (see supported time measurements) - unit: false, - - // Number - The number of steps of the above unit between ticks - unitStepSize: 1 - - // string - By default, no rounding is applied. To round, set to a supported time unit eg. 'week', 'month', 'year', etc. - round: false, - - // Number - By default, the week and therefore the scale starts on the locale defined week if the unit is 'week'. To override the start day of the week, set this to an integer between 1 and 7 - see http://momentjs.com/docs/#/get-set/iso-weekday/ - isoWeekday: false, - - // Moment js for each of the units. Replaces `displayFormat` - // To override, use a pattern string from http://momentjs.com/docs/#/displaying/format/ - displayFormats: { - 'millisecond': 'SSS [ms]', - 'second': 'h:mm:ss a', // 11:20:01 AM - 'minute': 'h:mm:ss a', // 11:20:01 AM - 'hour': 'MMM D, hA', // Sept 4, 5PM - 'day': 'll', // Sep 4 2015 - 'week': 'll', // Week 46, or maybe "[W]WW - YYYY" ? - 'month': 'MMM YYYY', // Sept 2015 - 'quarter': '[Q]Q - YYYY', // Q3 - 'year': 'YYYY', // 2015 - }, - // Sets the display format used in tooltip generation - tooltipFormat: '' - }, -} -``` - -The following time measurements are supported: - -```javascript -{ - 'millisecond': { - display: 'SSS [ms]', // 002 ms - maxStep: 1000, - }, - 'second': { - display: 'h:mm:ss a', // 11:20:01 AM - maxStep: 60, - }, - 'minute': { - display: 'h:mm:ss a', // 11:20:01 AM - maxStep: 60, - }, - 'hour': { - display: 'MMM D, hA', // Sept 4, 5PM - maxStep: 24, - }, - 'day': { - display: 'll', // Sep 4 2015 - maxStep: 7, - }, - 'week': { - display: 'll', // Week 46, or maybe "[W]WW - YYYY" ? - maxStep: 4.3333, - }, - 'month': { - display: 'MMM YYYY', // Sept 2015 - maxStep: 12, - }, - 'quarter': { - display: '[Q]Q - YYYY', // Q3 - maxStep: 4, - }, - 'year': { - display: 'YYYY', // 2015 - maxStep: false, - }, -} -``` - -### Radial Linear Scale -The radial linear scale is used specifically for the radar chart type. - -The radial linear scale extends the core scale class with the following tick template: - -```javascript -{ - animate: true, - lineArc: false, - position: "chartArea", - - angleLines: { - display: true, - color: "rgba(0, 0, 0, 0.1)", - lineWidth: 1 - }, - - // label settings - ticks: { - //Boolean - Show a backdrop to the scale label - showLabelBackdrop: true, - - //String - The colour of the label backdrop - backdropColor: "rgba(255,255,255,0.75)", - - //Number - The backdrop padding above & below the label in pixels - backdropPaddingY: 2, - - //Number - The backdrop padding to the side of the label in pixels - backdropPaddingX: 2, - - //Number - Limit the maximum number of ticks and gridlines - maxTicksLimit: 11, - }, - - pointLabels: { - //String - Point label font declaration - fontFamily: "'Arial'", - - //String - Point label font weight - fontStyle: "normal", - - //Number - Point label font size in pixels - fontSize: 10, - - //String - Point label font colour - fontColor: "#666", - - //Function - Used to determine point labels to show in scale - callback: function(pointLabel) { - return pointLabel; - } - }, -} -``` - -### Update Default Scale config -The default configuration for a scale can be easily changed using the scale service. Pass in a partial configuration that will be merged with the current scale default configuration. - -For example, to set the minimum value of 0 for all linear scales, you would do the following. Any linear scales created after this time would now have a minimum of 0. -``` -Chart.scaleService.updateScaleDefaults('linear', { - ticks: { - min: 0 - } -}) -``` diff --git a/docs/02-Scales.md b/docs/02-Scales.md new file mode 100644 index 000000000..a5b1f5260 --- /dev/null +++ b/docs/02-Scales.md @@ -0,0 +1,357 @@ +--- +title: Scales +anchor: scales +--- + +Scales in v2.0 of Chart.js are significantly more powerful, but also different than those of v1.0. +* Multiple X & Y axes are supported. +* A built-in label auto-skip feature detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally. +* Scale titles are supported +* New scale types can be extended without writing an entirely new chart type + + +### Common Configuration + +Every scale extends a core scale class with the following options: + +Name | Type | Default | Description +--- | --- | --- | --- +type | String | Chart specific. | Type of scale being employed. Custom scales can be created and registered with a string key. Options: ["category"](#scales-category-scale), ["linear"](#scales-linear-scale), ["logarithmic"](#scales-logarithmic-scale), ["time"](#scales-time-scale), ["radialLinear"](#scales-radial-linear-scale) +display | Boolean | true | If true, show the scale including gridlines, ticks, and labels. Overrides *gridLines.display*, *scaleLabel.display*, and *ticks.display*. +position | String | "left" | Position of the scale. Possible values are 'top', 'left', 'bottom' and 'right'. +beforeUpdate | Function | undefined | Callback called before the update process starts. Passed a single argument, the scale instance. +beforeSetDimensions | Function | undefined | Callback that runs before dimensions are set. Passed a single argument, the scale instance. +afterSetDimensions | Function | undefined | Callback that runs after dimensions are set. Passed a single argument, the scale instance. +beforeDataLimits | Function | undefined | Callback that runs before data limits are determined. Passed a single argument, the scale instance. +afterDataLimits | Function | undefined | Callback that runs after data limits are determined. Passed a single argument, the scale instance. +beforeBuildTicks | Function | undefined | Callback that runs before ticks are created. Passed a single argument, the scale instance. +afterBuildTicks | Function | undefined | Callback that runs after ticks are created. Useful for filtering ticks. Passed a single argument, the scale instance. +beforeTickToLabelConversion | Function | undefined | Callback that runs before ticks are converted into strings. Passed a single argument, the scale instance. +afterTickToLabelConversion | Function | undefined | Callback that runs after ticks are converted into strings. Passed a single argument, the scale instance. +beforeCalculateTickRotation | Function | undefined | Callback that runs before tick rotation is determined. Passed a single argument, the scale instance. +afterCalculateTickRotation | Function | undefined | Callback that runs after tick rotation is determined. Passed a single argument, the scale instance. +beforeFit | Function | undefined | Callback that runs before the scale fits to the canvas. Passed a single argument, the scale instance. +afterFit | Function | undefined | Callback that runs after the scale fits to the canvas. Passed a single argument, the scale instance. +afterUpdate | Function | undefined | Callback that runs at the end of the update process. Passed a single argument, the scale instance. +**gridLines** | Object | - | See [grid line configuration](#scales-grid-line-configuration) section. +**scaleLabel** | Object | | See [scale title configuration](#scales-scale-title-configuration) section. +**ticks** | Object | | See [ticks configuration](#scales-ticks-configuration) section. + +#### Grid Line Configuration + +The grid line configuration is nested under the scale configuration in the `gridLines` key. It defines options for the grid lines that run perpendicular to the axis. + +Name | Type | Default | Description +--- | --- | --- | --- +display | Boolean | true | +color | Color | "rgba(0, 0, 0, 0.1)" | Color of the grid lines. +lineWidth | Number | 1 | Stroke width of grid lines +drawBorder | Boolean | true | If true draw border on the edge of the chart +drawOnChartArea | Boolean | true | If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn +drawTicks | Boolean | true | If true, draw lines beside the ticks in the axis area beside the chart. +tickMarkLength | Number | 10 | Length in pixels that the grid lines will draw into the axis area. +zeroLineWidth | Number | 1 | Stroke width of the grid line for the first index (index 0). +zeroLineColor | Color | "rgba(0, 0, 0, 0.25)" | Stroke color of the grid line for the first index (index 0). +offsetGridLines | Boolean | false | If true, offset labels from grid lines. + +#### Scale Title Configuration + +The grid line configuration is nested under the scale configuration in the `scaleLabel` key. It defines options for the scale title. + +Name | Type | Default | Description +--- | --- | --- | --- +display | Boolean | false | +labelString | String | "" | The text for the title. (i.e. "# of People", "Response Choices") +fontColor | Color | "#666" | Font color for the scale title. +fontFamily| String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for the scale title, follows CSS font-family options. +fontSize | Number | 12 | Font size for the scale title. +fontStyle | String | "normal" | Font style for the scale title, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). + +#### Tick Configuration + +The grid line configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis. + +Name | Type | Default | Description +--- | --- | --- | --- +autoSkip | Boolean | true | If true, automatically calculates how many labels that can be shown and hides labels accordingly. Turn it off to show all labels no matter what +callback | Function | `function(value) { return '' + value; } ` | Returns the string representation of the tick value as it should be displayed on the chart. See [callback](#scales-creating-custom-tick-formats) section below. +display | Boolean | true | If true, show the ticks. +fontColor | Color | "#666" | Font color for the tick labels. +fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for the tick labels, follows CSS font-family options. +fontSize | Number | 12 | Font size for the tick labels. +fontStyle | String | "normal" | Font style for the tick labels, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). +labelOffset | Number | 0 | Distance in pixels to offset the label from the centre point of the tick (in the y direction for the x axis, and the x direction for the y axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* +maxRotation | Number | 90 | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* +minRotation | Number | 0 | Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* +mirror | Boolean | false | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* +padding | Number | 10 | Padding between the tick label and the axis. *Note: Only applicable to horizontal scales.* +reverse | Boolean | false | Reverses order of tick labels. + +#### Creating Custom Tick Formats + +The `callback` method may be used for advanced tick customization. In the following example, every label of the Y axis would be displayed in scientific notation. + +If the callback returns `null` or `undefined` the associated grid line will be hidden. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + yAxes: [{ + ticks: { + // Create scientific notation labels + callback: function(value, index, values) { + return value.toExponential(); + } + } + }] + } + } +}); +``` + +### Category Scale + +The category scale will be familiar to those who have used v1.0. Labels are drawn in from the labels array included in the chart data. + +#### Configuration Options + +The category scale has the following additional options that can be set. + +Name | Type | Default | Description +--- | --- | --- | --- +ticks.min | String | - | The minimum item to display. Must be a value in the `labels` array +ticks.max | String | - | The maximum item to display. Must be a value in the `labels` array +gridLines.offsetGridLines | Boolean | - | If true, labels are shifted to be between grid lines. This is used in the bar chart. + + +### Linear Scale + +The linear scale is use to chart numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to use one of these scales for the x axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis. + +#### Configuration Options + +The following options are provided by the linear scale. They are all located in the `ticks` sub options. + +Name | Type | Default | Description +--- | --- | --- | --- +beginAtZero | Boolean | - | if true, scale will inclulde 0 if it is not already included. +min | Number | - | User defined minimum number for the scale, overrides minimum value from data. +max | Number | - | User defined maximum number for the scale, overrides maximum value from data. +maxTicksLimit | Number | 11 | Maximum number of ticks and gridlines to show. If not defined, it will limit to 11 ticks but will show all gridlines. +stepSize | Number | - | User defined fixed step size for the scale. If set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. +stepSize | Number | - | if defined, it can be used along with the min and the max to give a custom number of steps. See the example below. +suggestedMax | Number | - | User defined maximum number for the scale, overrides maximum value *except for if* it is lower than the maximum value. +suggestedMin | Number | - | User defined minimum number for the scale, overrides minimum value *except for if* it is higher than the minimum value. + +#### Example Configuration + +The following example creates a line chart with a vertical axis that goes from 0 to 5 in 0.5 sized steps. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + yAxes: [{ + ticks: { + max: 5, + min: 0, + stepSize: 0.5 + } + }] + } + } +}); +``` + +### Logarithmic Scale + +The logarithmic scale is use to chart numerical data. It can be placed on either the x or y axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. + +#### Configuration Options + +The following options are provided by the logarithmic scale. They are all located in the `ticks` sub options. + +Name | Type | Default | Description +--- | --- | --- | --- +min | Number | - | User defined minimum number for the scale, overrides minimum value from data. +max | Number | - | User defined maximum number for the scale, overrides maximum value from data. + +#### Example Configuration + +The following example creates a chart with a logarithmic X axis that ranges from 1 to 1000. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + xAxes: [{ + type: 'logarithmic', + position: 'bottom', + ticks: { + min: 1, + max: 1000 + } + }] + } +}) +``` + +### Time Scale + +The time scale is used to display times and dates. It can only be placed on the X axis. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. + +#### Configuration Options + +The following options are provided by the logarithmic scale. They are all located in the `time` sub options. + +Name | Type | Default | Description +--- | --- | --- | --- +displayFormats | Object | - | See [Display Formats](#scales-display-formats) section below. +isoWeekday | Boolean | false | If true and the unit is set to 'week', iso weekdays will be used. +max | [Time](#scales-date-formats) | - | If defined, this will override the data maximum +min | [Time](#scales-date-formats) | - | If defined, this will override the data minimum +parser | String or Function | - | If defined as a string, it is interpreted as a custom format to be used by moment to parse the date. If this is a function, it must return a moment.js object given the appropriate data value. +round | String | - | If defined, dates will be rounded to the start of this unit. See [Time Units](#scales-time-units) below for the allowed units. +tooltipFormat | String | '' | The moment js format string to use for the tooltip. +unit | String | - | If defined, will force the unit to be a certain type. See [Time Units](#scales-time-units) section below for details. +unitStepSize | Number | 1 | The number of units between grid lines. + +#### Date Formats + +When providing data for the time scale, Chart.js supports all of the formats that Moment.js accepts. See [Moment.js docs](http://momentjs.com/docs/#/parsing/) for details. + +#### Display Formats + +The following display formats are used to configure how different time units are formed into strings for the axis tick marks. See [moment.js](http://momentjs.com/docs/#/displaying/format/) for the allowable format strings. + +Name | Default +--- | --- +millisecond | 'SSS [ms]' +second | 'h:mm:ss a' +minute | 'h:mm:ss a' +hour | 'MMM D, hA' +day | 'll' +week | 'll' +month | 'MMM YYYY' +quarter | '[Q]Q - YYYY' +year | 'YYYY' + +For example, to set the display format for the 'quarter' unit to show the month and year, the following config would be passed to the chart constructor. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + xAxes: [{ + type: 'time', + time: { + displayFormats: { + quarter: 'MMM YYYY' + } + } + }] + } + } +}) +``` + +#### Time Units + +The following time measurements are supported. The names can be passed as strings to the `time.unit` config option to force a certain unit. + +* millisecond +* second +* minute +* hour +* day +* week +* month +* quarter +* year + +For example, to create a chart with a time scale that always displayed units per month, the following config could be used. + +```javascript +var chartInstance = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + xAxes: [{ + time: { + unit: 'month' + } + }] + } + } +}) +``` + +### Radial Linear Scale + +The radial linear scale is used specifically for the radar and polar are chart types. It overlays the chart area, rather than being positioned on one of the edges. + +#### Configuration Options + +The following additional configuration options are provided by the radial linear scale. + +Name | Type | Default | Description +--- | --- | --- | --- +lineArc | Boolean | false | If true, circular arcs are used else straight lines are used. The former is used by the polar area chart and the latter by the radar chart +angleLines | Object | - | See the [Angle Lines](#scales-angle-line-options) section below for details. +pointLabels | Object | - | See the [Point Label](#scales-point-label) section below for details. +ticks | Object | - | See the Ticks table below for options. + +#### Angle Line Options + +The following options are used to configure angled lines that radiate from the center of the chart to the point labels. They can be found in the `angleLines` sub options. Note that these options only apply if `lineArc` is false. + +Name | Type | Default | Description +--- | --- | --- | --- +display | Boolean | true | If true, angle lines are shown. +color | Color | 'rgba(0, 0, 0, 0.1)' | Color of angled lines +lineWidth | Number | 1 | Width of angled lines + +#### Point Label Options + +The following options are used to configure the point labels that are shown on the perimeter of the scale. They can be found in the `pointLabel` sub options. Note that these options only apply if `lineArc` is false. + +Name | Type | Default | Description +--- | --- | --- | --- +callback | Function | - | Callback function to transform data label to axis label +fontColor | Color | '#666' | Font color +fontFamily | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family to render +fontSize | Number | 10 | Font size in pixels +fontStyle | String | 'normal' | Font Style to use + + +#### Tick Options + +Name | Type | Default | Description +--- | --- | --- | --- +backdropColor | Color | 'rgba(255, 255, 255, 0.75)' | Color of label backdrops +backdropPaddingX | Number | 2 | Horizontal padding of label backdrop +backdropPaddingY | Number | 2 | Vertical padding of label backdrop +maxTicksLimit | Number | 11 | Maximum number of ticks and gridlines to show. If not defined, it will limit to 11 ticks but will show all gridlines. +showLabelBackdrop | Boolean | true | If true, draw a background behind the tick labels + +### Update Default Scale config + +The default configuration for a scale can be easily changed using the scale service. Pass in a partial configuration that will be merged with the current scale default configuration. + +For example, to set the minimum value of 0 for all linear scales, you would do the following. Any linear scales created after this time would now have a minimum of 0. +``` +Chart.scaleService.updateScaleDefaults('linear', { + ticks: { + min: 0 + } +}) +``` diff --git a/docs/02-Line-Chart.md b/docs/03-Line-Chart.md similarity index 68% rename from docs/02-Line-Chart.md rename to docs/03-Line-Chart.md index 92736614d..d15de299a 100644 --- a/docs/02-Line-Chart.md +++ b/docs/03-Line-Chart.md @@ -3,15 +3,13 @@ title: Line Chart anchor: line-chart --- ### Introduction -A line chart is a way of plotting data points on a line. - -Often, it is used to show trend data, and the comparison of two data sets. +A line chart is a way of plotting data points on a line. Often, it is used to show trend data, and the comparison of two data sets.
-### Example usage +### Example Usage ```javascript var myLineChart = new Chart(ctx, { type: 'line', @@ -27,7 +25,8 @@ var myLineChart = Chart.Line(ctx, { options: options }); ``` -### Data structure + +### Data Structure The following options can be included in a line chart dataset to configure options for that specific dataset. @@ -35,7 +34,7 @@ All point* properties can be specified as an array. If these are set to an array Property | Type | Usage --- | --- | --- -data | `Array` | The data to plot in a line +data | See [data point](#line-chart-data-points) section | The data to plot in a line label | `String` | The label for the dataset which appears in the legend and tooltips xAxisID | `String` | The ID of the x axis to plot this dataset on yAxisID | `String` | The ID of the y axis to plot this dataset on @@ -57,7 +56,7 @@ pointHitRadius | `Number or Array` | The pixel size of the non-displayed pointHoverBackgroundColor | `Color or Array` | Point background color when hovered pointHoverBorderColor | `Color or Array` | Point border color when hovered pointHoverBorderWidth | `Number or Array` | Border width of point when hovered -pointStyle | `String or Array` | The style of point. Options include 'circle', 'triangle', 'rect', 'rectRot', 'cross', 'crossRot', 'star', 'line', and 'dash' +pointStyle | `String, Array, Image, Array` | The style of point. Options are 'circle', 'triangle', 'rect', 'rectRot', 'cross', 'crossRot', 'star', 'line', and 'dash'. If the option is an image, that image is drawn on the canvas using `drawImage`. An example data object using these attributes is shown below. ```javascript @@ -89,39 +88,61 @@ var data = { }; ``` -The line chart requires an array of labels. This labels are shown on the X axis. There must be one label for each data point. More labels than datapoints are allowed, in which case the line ends at the last data point. +The line chart usually requires an array of labels. This labels are shown on the X axis. There must be one label for each data point. More labels than datapoints are allowed, in which case the line ends at the last data point. 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. The label key on each dataset is optional, and can be used when generating a scale for the chart. -### Chart options +### Data Points -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. +The data passed to the chart can be passed in two formats. The most common method is to pass the data array as an array of numbers. In this case, the `data.labels` array must be specified and must contain a label for each point. -The default options for line chart are defined in `Chart.defaults.line`. +The alternate is used for sparse datasets. Data is specified using an object containing `x` and `y` properties. This is used for scatter charts as documented below. + +### Scatter Line Charts + +Scatter line charts can be created by changing the X axis to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. The example below creates a scatter chart with 3 points. + +```javascript +var scatterChart = new Chart(ctx, { + type: 'line', + data: { + datasets: [{ + label: 'Scatter Dataset', + data: [{ + x: -10, + y: 0 + }, { + x: 0, + y: 10 + }, { + x: 10, + y: 5 + }] + }] + }, + options: { + scales: { + xAxes: [{ + type: 'linear', + position: 'bottom' + }] + } + } +}); +``` + +### Chart Options + +These are the customisation options specific to Line charts. These options are merged with the [global chart configuration options](#chart-configuration-global-configuration), and form the options of the chart. Name | Type | Default | Description --- | --- | --- | --- showLines | Boolean | true | If false, the lines between points are not drawn -stacked | Boolean | false | If true, lines stack on top of each other along the y axis. -*hover*.mode | String | "label" | Label's hover mode. "label" is used since the x axis displays data by the index in the dataset. -elements | Object | - | - -*elements*.point | Object | - | - -*elements.point*.radius | Number | `3` | Defines the size of the Point shape. Can be set to zero to skip rendering a point. -scales | Object | - | - -*scales*.xAxes | Array | `[{type:"category","id":"x-axis-0"}]` | Defines all of the x axes used in the chart. See the [scale documentation](#scales) for details on the available options. -*Options for xAxes* | | | -type | String | "category" | As defined in ["Category"](#scales-category-scale). -id | String | "x-axis-0" | Id of the axis so that data can bind to it. - | | | - *scales*.yAxes | Array | `[{type:"linear","id":"y-axis-0"}]` | Defines all of the y axes used in the chart. See the [scale documentation](#scales) for details on the available options. - *Options for yAxes* | | | - type | String | "linear" | As defined in ["Linear"](#scales-linear-scale). - id | String | "y-axis-0" | Id of the axis so that data can bind to it. You can override these for your `Chart` instance by passing a member `options` into the `Line` method. -For example, we could have a line chart display without an x axis by doing the following. The config merge is smart enough to handle arrays so that you do not need to specify all axis settings to change one thing. +For example, we could have a line chart display without an X axis by doing the following. The config merge is smart enough to handle arrays so that you do not need to specify all axis settings to change one thing. ```javascript new Chart(ctx, { @@ -135,8 +156,24 @@ new Chart(ctx, { } } }); -// This will create a chart with all of the default options, merged from the global config, -// and the Line chart defaults, but this particular instance will have the x axis not displaying. ``` We can also change these defaults values for each Line type that is created, this object is available at `Chart.defaults.line`. + +### Stacked Charts + +Stacked area charts can be created by setting the Y axis to a stacked configuration. The following example would have stacked lines. + +```javascript +var stackedLine = new Chart(ctx, { + type: 'line', + data: data, + options: { + scales: { + yAxes: [{ + stacked: true + }] + } + } +}); +``` diff --git a/docs/03-Bar-Chart.md b/docs/04-Bar-Chart.md similarity index 98% rename from docs/03-Bar-Chart.md rename to docs/04-Bar-Chart.md index c2795dece..a0b1440c7 100644 --- a/docs/03-Bar-Chart.md +++ b/docs/04-Bar-Chart.md @@ -12,7 +12,7 @@ It is sometimes used to show trend data, and the comparison of multiple data set -### Example usage +### Example Usage ```javascript var myBarChart = new Chart(ctx, { type: 'bar', @@ -31,7 +31,7 @@ var myBarChart = new Chart(ctx, { }); ``` -### Data structure +### Data Structure The following options can be included in a bar chart dataset to configure options for that specific dataset. Some properties can be specified as an array. If these are set to an array value, the first value applies to the first bar, the second value to the second bar, and so on. @@ -73,7 +73,7 @@ We have an array of labels too for display. In the example, we are showing the s ### Chart Options -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. +These are the customisation options specific to Bar charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. The default options for bar chart are defined in `Chart.defaults.bar`. diff --git a/docs/04-Radar-Chart.md b/docs/05-Radar-Chart.md similarity index 97% rename from docs/04-Radar-Chart.md rename to docs/05-Radar-Chart.md index 8eb40547b..ce98dc4e9 100644 --- a/docs/04-Radar-Chart.md +++ b/docs/05-Radar-Chart.md @@ -12,7 +12,7 @@ They are often useful for comparing the points of two or more different data set -### Example usage +### Example Usage ```javascript var myRadarChart = new Chart(ctx, { @@ -22,7 +22,7 @@ var myRadarChart = new Chart(ctx, { }); ``` -### Data structure +### Data Structure The following options can be included in a radar chart dataset to configure options for that specific dataset. @@ -88,7 +88,7 @@ The label key on each dataset is optional, and can be used when generating a sca ### Chart Options -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. +These are the customisation options specific to Radar charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. The default options for radar chart are defined in `Chart.defaults.radar`. diff --git a/docs/05-Polar-Area-Chart.md b/docs/06-Polar-Area-Chart.md similarity index 96% rename from docs/05-Polar-Area-Chart.md rename to docs/06-Polar-Area-Chart.md index d0d4d3047..3b94b7318 100644 --- a/docs/05-Polar-Area-Chart.md +++ b/docs/06-Polar-Area-Chart.md @@ -11,7 +11,7 @@ This type of chart is often useful when we want to show a comparison data simila -### Example usage +### Example Usage ```javascript new Chart(ctx, { @@ -21,7 +21,7 @@ new Chart(ctx, { }); ``` -### Data structure +### Data Structure The following options can be included in a polar area chart dataset to configure options for that specific dataset. @@ -70,9 +70,9 @@ var data = { ``` 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. -### Chart options +### Chart Options -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. +These are the customisation options specific to Polar Area charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. Name | Type | Default | Description --- | --- | --- | --- diff --git a/docs/06-Pie-Doughnut-Chart.md b/docs/07-Pie-Doughnut-Chart.md similarity index 96% rename from docs/06-Pie-Doughnut-Chart.md rename to docs/07-Pie-Doughnut-Chart.md index a46b0bafa..3347d7309 100644 --- a/docs/06-Pie-Doughnut-Chart.md +++ b/docs/07-Pie-Doughnut-Chart.md @@ -20,7 +20,7 @@ They are also registered under two aliases in the `Chart` core. Other than their
-### Example usage +### Example Usage ```javascript // For a pie chart @@ -40,7 +40,7 @@ var myDoughnutChart = new Chart(ctx, { }); ``` -### Data structure +### Data Structure Property | Type | Usage --- | --- | --- @@ -81,9 +81,9 @@ var data = { 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. You can also add an array of background colors. The color attributes should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL. -### Chart options +### Chart Options -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. +These are the customisation options specific to Pie & Doughnut charts. These options are merged with the [global chart configuration options](#global-chart-configuration), and form the options of the chart. Name | Type | Default | Description --- | --- | --- | --- diff --git a/docs/07-Bubble-Chart.md b/docs/08-Bubble-Chart.md similarity index 98% rename from docs/07-Bubble-Chart.md rename to docs/08-Bubble-Chart.md index 9bd9c8c02..cca366406 100644 --- a/docs/07-Bubble-Chart.md +++ b/docs/08-Bubble-Chart.md @@ -10,7 +10,7 @@ A bubble chart is used to display three dimensions of data at the same time. The
-### Example usage +### Example Usage ```javascript // For a bubble chart @@ -21,7 +21,7 @@ var myBubbleChart = new Chart(ctx,{ }); ``` -### Data structure +### Data Structure Property | Type | Usage --- | --- | --- @@ -77,7 +77,7 @@ Data for the bubble chart is passed in the form of an object. The object must im } ``` -### Chart options +### Chart Options The bubble chart has no unique configuration options. To configure options common to all of the bubbles, the point element options are used. diff --git a/docs/08-Advanced.md b/docs/09-Advanced.md similarity index 99% rename from docs/08-Advanced.md rename to docs/09-Advanced.md index 3b8eacc83..ff2810f85 100644 --- a/docs/08-Advanced.md +++ b/docs/09-Advanced.md @@ -4,7 +4,7 @@ anchor: advanced-usage --- -### Prototype methods +### Prototype Methods 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. @@ -161,7 +161,7 @@ var myPieChart = new Chart(ctx, { See `sample/line-customTooltips.html` for examples on how to get started. -### Writing new scale types +### Writing New Scale Types Starting with Chart.js 2.0 scales can be individually extended. Scales should always derive from Chart.Scale. @@ -293,7 +293,7 @@ The Core.Scale base class also has some utility functions that you may find usef } ``` -### Writing new chart types +### Writing New Chart Types Chart.js 2.0 introduces the concept of controllers for each dataset. Like scales, new controllers can be written as needed. @@ -355,7 +355,7 @@ The following methods may optionally be overridden by derived dataset controller } ``` -### Extending existing chart types +### Extending Existing Chart Types Extending or replacing an existing controller type is easy. Simply replace the constructor for one of the built in types with your own. diff --git a/docs/09-Notes.md b/docs/10-Notes.md similarity index 100% rename from docs/09-Notes.md rename to docs/10-Notes.md