# Animations

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.

    # Animation configuration

    Animation configuration consists of 3 keys.

    Name Type Details
    animation object animation
    animations object animations
    transitions object transitions

    These keys can be configured in following paths:

    • `` - chart options
    • datasets[type] - dataset type options
    • overrides[type] - chart type options

    These paths are valid under defaults for global confuguration and options for instance configuration.

    # animation

    The default configuration is defined here: core.animations.js

    Namespace: options.animation

    Name Type Default Description
    duration number 1000 The number of milliseconds an animation takes.
    easing string 'easeOutQuart' Easing function to use. more...
    delay number undefined Delay before starting the animations.
    loop boolean undefined If set to true, the animations loop endlessly.

    These defaults can be overridden in options.animation or dataset.animation and tooltip.animation. These keys are also Scriptable.

    # animations

    Animations options configures which element properties are animated and how. In addition to the main animation configuration, the following options are available:

    Namespace: options.animations[animation]

    Name Type Default Description
    properties string[] key The property names this configuration applies to. Defaults to the key name of this object.
    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.
    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
    fn <T>(from: T, to: T, factor: number) => T; undefined Optional custom interpolator, instead of using a predefined interpolator from type

    # Default animations

    Name Option Value
    numbers properties ['x', 'y', 'borderWidth', 'radius', 'tension']
    numbers type 'number'
    colors properties ['color', 'borderColor', 'backgroundColor']
    colors type 'color'

    Note

    These default animations are overridden by most of the dataset controllers.

    # transitions

    The core transitions are 'active', 'hide', 'reset', 'resize', 'show'. A custom transition can be used by passing a custom mode to update. Transition extends the main animation configuration and 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.
    'show' animations.visible { type: 'boolean', duration: 0 } Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
    'hide' animations.colors { type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' } Colors are faded to transparent when dataset id hidden using legend / api.
    'hide' animations.visible { type: 'boolean', easing: 'easeInExpo' } Visibility is changed to false at a very late phase of animation

    # Disabling animation

    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.

    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
    

    # 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 (opens new window).

    # Animation Callbacks

    The animation configuration provides callbacks which are useful for synchronizing an external draw to the chart animation. The callbacks can be set only at main animation configuration.

    Namespace: options.animation

    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.

    The callback is passed the following object:

    {
      // Chart object
      chart: Chart,
      // Number of animations still in progress
      currentStep: number,
      // `true` for the initial animation of the chart
      initial: boolean,
      // Total number of animations at the start of current animation
      numSteps: number,
    }
    

    The following example fills a progress bar during the chart animation.

    const chart = new Chart(ctx, {
        type: 'line',
        data: data,
        options: {
            animation: {
                onProgress: function(animation) {
                    progress.value = animation.currentStep / animation.numSteps;
                }
            }
        }
    });
    

    Another example usage of these callbacks can be found on Github (opens new window): this sample displays a progress bar showing how far along the animation is.

    Last Updated: 12/23/2021, 6:55:39 PM