2021-03-30 16:32:39 +02:00
# Animations
2020-05-21 22:43:36 +02:00
Chart.js animates charts out of the box. A number of options are provided to configure how the animation looks and how long it takes.
2021-03-30 16:32:39 +02:00
:::: tabs
::: tab "Looping tension [property]"
```js chart-editor
// < block:setup:1 >
const data = {
labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
datasets: [{
label: 'Looping tension',
data: [65, 59, 80, 81, 26, 55, 40],
fill: false,
borderColor: 'rgb(75, 192, 192)',
}]
};
// < / block:setup >
// < block:config:0 >
const config = {
type: 'line',
data: data,
options: {
animations: {
tension: {
duration: 1000,
easing: 'linear',
from: 1,
to: 0,
loop: true
}
},
scales: {
y: { // defining min and max so hiding the dataset does not change scale range
min: 0,
max: 100
2020-05-21 22:43:36 +02:00
}
2021-03-30 16:32:39 +02:00
}
}
};
// < / block:config >
module.exports = {
actions: [],
config: config,
};
2020-05-21 22:43:36 +02:00
```
2021-03-30 16:32:39 +02:00
:::
::: tab "Hide and show [mode]"
```js chart-editor
// < block:setup:1 >
const data = {
labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
datasets: [{
label: 'Try hiding me',
data: [65, 59, 80, 81, 26, 55, 40],
fill: false,
borderColor: 'rgb(75, 192, 192)',
}]
};
// < / block:setup >
// < block:config:0 >
const config = {
type: 'line',
data: data,
options: {
transitions: {
show: {
animations: {
x: {
from: 0
},
y: {
from: 0
}
}
2020-05-21 22:43:36 +02:00
},
2021-03-30 16:32:39 +02:00
hide: {
animations: {
x: {
to: 0
2021-02-20 15:02:22 +01:00
},
2021-03-30 16:32:39 +02:00
y: {
to: 0
2020-05-21 22:43:36 +02:00
}
2021-02-20 15:02:22 +01:00
}
2020-05-21 22:43:36 +02:00
}
2021-03-30 16:32:39 +02:00
}
}
};
// < / block:config >
module.exports = {
actions: [],
config: config,
};
2020-05-21 22:43:36 +02:00
```
2021-03-30 16:32:39 +02:00
:::
::::
2020-05-21 22:43:36 +02:00
2021-02-20 15:02:22 +01:00
## Animation configuration
Animation configuration consists of 3 keys.
| Name | Type | Details
| ---- | ---- | -------
| animation | `object` | [animation ](#animation )
| animations | `object` | [animations ](#animations )
| transitions | `object` | [transitions ](#transitions )
These keys can be configured in following paths:
* `` - chart options
* `datasets[type]` - dataset type options
2021-03-06 16:34:52 +01:00
* `overrides[type]` - chart type options
2020-05-21 22:43:36 +02:00
2022-01-27 15:24:55 +01:00
These paths are valid under `defaults` for global configuration and `options` for instance configuration.
2021-02-20 15:02:22 +01:00
## animation
2021-03-30 16:32:39 +02:00
The default configuration is defined here: < a href = "https://github.com/chartjs/Chart.js/blob/master/src/core/core.animations.js" target = "_blank" > core.animations.js< / a >
2021-02-20 15:02:22 +01:00
Namespace: `options.animation`
2020-05-21 22:43:36 +02:00
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `duration` | `number` | `1000` | The number of milliseconds an animation takes.
| `easing` | `string` | `'easeOutQuart'` | Easing function to use. [more... ](#easing )
| `delay` | `number` | `undefined` | Delay before starting the animations.
| `loop` | `boolean` | `undefined` | If set to `true` , the animations loop endlessly.
2020-07-31 15:49:17 +02:00
2020-12-18 18:46:54 +01:00
These defaults can be overridden in `options.animation` or `dataset.animation` and `tooltip.animation` . These keys are also [Scriptable ](../general/options.md#scriptable-options ).
2020-07-31 15:49:17 +02:00
2021-02-20 15:02:22 +01:00
## animations
2020-07-31 15:49:17 +02:00
2021-02-20 15:02:22 +01:00
Animations options configures which element properties are animated and how.
In addition to the main [animation configuration ](#animation-configuration ), the following options are available:
2020-07-31 15:49:17 +02:00
2021-02-20 15:02:22 +01:00
Namespace: `options.animations[animation]`
2021-02-19 17:44:05 +01:00
2020-07-31 15:49:17 +02:00
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
2021-02-20 15:02:22 +01:00
| `properties` | `string[]` | `key` | The property names this configuration applies to. Defaults to the key name of this object.
2020-05-21 22:43:36 +02:00
| `type` | `string` | `typeof property` | Type of property, determines the interpolator used. Possible values: `'number'` , `'color'` and `'boolean'` . Only really needed for `'color'` , because `typeof` does not get that right.
2020-12-18 21:03:01 +01:00
| `from` | `number` \|`Color` \|`boolean` | `undefined` | Start value for the animation. Current value is used when `undefined`
| `to` | `number` \|`Color` \|`boolean` | `undefined` | End value for the animation. Updated value is used when `undefined`
2020-12-18 18:46:54 +01:00
| `fn` | < code > < T> (from: T, to: T, factor: number) => T;</ code > | `undefined` | Optional custom interpolator, instead of using a predefined interpolator from `type` |
2020-07-31 15:49:17 +02:00
2021-02-20 15:02:22 +01:00
### Default animations
2020-05-21 22:43:36 +02:00
| Name | Option | Value
| ---- | ------ | -----
2020-12-22 16:22:25 +01:00
| `numbers` | `properties` | `['x', 'y', 'borderWidth', 'radius', 'tension']`
2021-02-20 15:02:22 +01:00
| `numbers` | `type` | `'number'`
| `colors` | `properties` | `['color', 'borderColor', 'backgroundColor']`
2020-05-21 22:43:36 +02:00
| `colors` | `type` | `'color'`
2021-03-31 00:19:45 +02:00
:::tip Note
2021-02-20 15:02:22 +01:00
These default animations are overridden by most of the dataset controllers.
2020-05-21 22:43:36 +02:00
:::
2021-02-20 15:02:22 +01:00
## transitions
The core transitions are `'active'` , `'hide'` , `'reset'` , `'resize'` , `'show'` .
2021-03-11 07:19:33 +01:00
A custom transition can be used by passing a custom `mode` to [update ](../developers/api.md#updatemode ).
2021-02-20 15:02:22 +01:00
Transition extends the main [animation configuration ](#animation-configuration ) and [animations configuration ](#animations-configuration ).
### Default transitions
Namespace: `options.transitions[mode]`
| Mode | Option | Value | Description
| -----| ------ | ----- | -----
| `'active'` | animation.duration | 400 | Override default duration to 400ms for hover animations
| `'resize'` | animation.duration | 0 | Override default duration to 0ms (= no animation) for resize
| `'show'` | animations.colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], from: 'transparent' }` | Colors are faded in from transparent when dataset is shown using legend / [api ](../developers/api.md#showdatasetIndex ).
2022-01-27 15:24:55 +01:00
| `'show'` | animations.visible | `{ type: 'boolean', duration: 0 }` | Dataset visibility is immediately changed to true so the color transition from transparent is visible.
2021-02-20 15:02:22 +01:00
| `'hide'` | animations.colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api ](../developers/api.md#hidedatasetIndex ).
| `'hide'` | animations.visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false at a very late phase of animation
2020-07-31 15:49:17 +02:00
## Disabling animation
2020-05-21 22:43:36 +02:00
2020-12-18 18:46:54 +01:00
To disable an animation configuration, the animation node must be set to `false` , with the exception for animation modes which can be disabled by setting the `duration` to `0` .
2020-07-31 15:49:17 +02:00
```javascript
2021-02-20 15:02:22 +01:00
chart.options.animation = false; // disables all animations
chart.options.animations.colors = false; // disables animation defined by the collection of 'colors' properties
chart.options.animations.x = false; // disables animation defined by the 'x' property
chart.options.transitions.active.animation.duration = 0; // disables the animation for 'active' mode
2020-07-31 15:49:17 +02:00
```
2020-05-21 22:43:36 +02:00
## Easing
Available options are:
* `'linear'`
* `'easeInQuad'`
* `'easeOutQuad'`
* `'easeInOutQuad'`
* `'easeInCubic'`
* `'easeOutCubic'`
* `'easeInOutCubic'`
* `'easeInQuart'`
* `'easeOutQuart'`
* `'easeInOutQuart'`
* `'easeInQuint'`
* `'easeOutQuint'`
* `'easeInOutQuint'`
* `'easeInSine'`
* `'easeOutSine'`
* `'easeInOutSine'`
* `'easeInExpo'`
* `'easeOutExpo'`
* `'easeInOutExpo'`
* `'easeInCirc'`
* `'easeOutCirc'`
* `'easeInOutCirc'`
* `'easeInElastic'`
* `'easeOutElastic'`
* `'easeInOutElastic'`
* `'easeInBack'`
* `'easeOutBack'`
* `'easeInOutBack'`
* `'easeInBounce'`
* `'easeOutBounce'`
* `'easeInOutBounce'`
See [Robert Penner's easing equations ](http://robertpenner.com/easing/ ).
## Animation Callbacks
2020-12-18 18:46:54 +01:00
The animation configuration provides callbacks which are useful for synchronizing an external draw to the chart animation.
2020-07-31 15:49:17 +02:00
The callbacks can be set only at main [animation configuration ](#animation-configuration ).
2021-02-19 17:44:05 +01:00
Namespace: `options.animation`
2020-07-31 15:49:17 +02:00
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `onProgress` | `function` | `null` | Callback called on each step of an animation.
| `onComplete` | `function` | `null` | Callback called when all animations are completed.
2020-12-18 18:46:54 +01:00
The callback is passed the following object:
2020-05-21 22:43:36 +02:00
```javascript
{
2021-04-17 14:09:22 +02:00
// Chart object
chart: Chart,
2020-05-21 22:43:36 +02:00
2021-04-17 14:09:22 +02:00
// Number of animations still in progress
currentStep: number,
2020-05-21 22:43:36 +02:00
2021-04-17 14:09:22 +02:00
// `true` for the initial animation of the chart
initial: boolean,
// Total number of animations at the start of current animation
numSteps: number,
2020-05-21 22:43:36 +02:00
}
```
The following example fills a progress bar during the chart animation.
```javascript
2021-10-13 20:51:33 +02:00
const chart = new Chart(ctx, {
2020-05-21 22:43:36 +02:00
type: 'line',
data: data,
options: {
animation: {
onProgress: function(animation) {
2020-12-18 18:46:54 +01:00
progress.value = animation.currentStep / animation.numSteps;
2020-05-21 22:43:36 +02:00
}
}
}
});
```
2022-02-22 14:37:33 +01:00
Another example usage of these callbacks can be found [in this progress bar sample. ](../samples/advanced/progress-bar.md ) which displays a progress bar showing how far along the animation is.