Skip to main content
Version: 5.4

Animating charts

Chart.JS animates charts out of the box and Charba does not change this behavior. A number of options are provided to configure how the animation looks and how long it takes.

The animation configuration consists in 3 different elements:

  1. Animation to configure the common animation options.
  2. Animations to configure the common animation options for a specific sets of element(like bar, point, arc and line) properties.
  3. Transitions to configure the animation and animations options for a specific update mode.

Animation

Animation is used to configure the base options to animate the chart.

To get, change and apply own properties, you can invoke the set and get methods, as following:

// sets and gets duration option to the animation of the chart
chart.getOptions().getAnimation().setDuration(2000);

int duration = chart.getOptions().getAnimation().getDuration();

The default values are set in global defaults options, see default global animation options.

The following animation options are available.

NameTypeScriptableDescription
animateRotateboolean-If true, the chart will animate in with a rotation animation.
animateScaleboolean-If true, will animate scaling the chart from the center outwards.
delayintYesDelay in milliseconds before starting the animations.
durationintYesThe number of milliseconds an animation takes.
easingEasingYesEasing function to use.
See Robert Penner's easing equations for more details.
loopbooleanYesIf set to true, the animations loop endlessly.

Scriptable

Scriptable options at animation level accept a callback which is called for each of the underlying data values. See more details in Configuring charts section.

// creates chart
BarChart chart = new BarChart();
// gets options
BarOptions options = chart.getOptions();
// sets the animation option by a callback
options.getAnimation().setDuration(new DurationCallback() {

@Override
public Integer invoke(DatasetContext context) {
// logic
return duration;
}
});

The following options can be set by a callback:

NameCallbackReturned types
delayDelayCallbackdouble
durationDurationCallbackdouble
easingEasingCallbackEasing
loopLoopCallbackboolean

Animations

Animations options configures which element properties are animated and how.

The animations element is a container of configurations which can be stored and retrieved by a key.

To get, change and apply own properties, you can invoke the set and get methods, as following:

// creates my animations key, setting it as a collection of properties
// which are numbers
AnimationCollectionKey key = AnimationCollectionKey.create("myKey", AnimationType.NUMBER);
// creates and gets an animation configuration item by my key
AnimationCollection animationCollection = chart.getOptions().getAnimations().create(key);
// sets and gets duration option to the animation configuration
animationCollection.setDuration(2000);

int duration = animationCollection.getDuration();

The default values are set in global defaults options, see default global animations options.

The following options are available in animation collection object:

NameTypeScriptableDescription
delayintYesDelay in milliseconds before starting the animations.
durationintYesThe number of milliseconds an animation takes.
easingEasingYesEasing function to use.
See Robert Penner's easing equations for more details.
fromboolean - double - String - IsColorYesStart value for the animation.
loopbooleanYesIf set to true, the animations loop endlessly.
propertiesAnimationPropertyKey[]The properties of elements to use to animate.
typeAnimationTypeType of property, determines the interpolator used.
toboolean - double - String - IsColorYesEnd value for the animation.

Default animations

Chart.JS provides a default configuration for every specific animation type:

AnimationTypeDefaultAnimationCollectionKeyProperties
NUMBERSNUMBERSDefaultAnimationPropertyKey.X,
DefaultAnimationPropertyKey.Y,
DefaultAnimationPropertyKey.BORDER_WIDTH,
DefaultAnimationPropertyKey.RADIUS,
DefaultAnimationPropertyKey.TENSION
COLORSCOLORSDefaultAnimationPropertyKey.COLOR, DefaultAnimationPropertyKey.BORDER_COLOR, DefaultAnimationPropertyKey.BACKGROUND_COLOR
BOOLEANVISIBLEDefaultAnimationPropertyKey.VISIBLE
info

These default animations are overridden by most of the charts default configuration.

Scriptable animations

Scriptable options at animations level accept a callback which is called for each of the underlying data values. See more details in Configuring charts section.

// creates chart
BarChart chart = new BarChart();
// gets options
BarOptions options = chart.getOptions();
// creates animations configuration
AnimationCollection animationCollection = options.getAnimations().create(DefaultAnimationCollectionKey.NUMBERS);
// sets the animation option by a callback
animationCollection.setFrom(new FromCallback() {

@Override
public Double invoke(DatasetContext context) {
// logic
return from;
}
});

The following options can be set by a callback:

NameCallbackReturned types
delayDelayCallbackdouble
durationDurationCallbackdouble
easingEasingCallbackEasing
fromFromCallbackboolean - double - String - IsColor
loopLoopCallbackboolean
toToCallbackboolean - double - String - IsColor

Transitions

The transitions are a set of animation configuration related to a specific update mode.

Every transition animation configuration contains an instance of Animation and one of Animations to configure the animation for a specific mode.

// creates a custom mode
TransitionKey mode = TransitionKey.create("myMode");
// creates an animation transitions configuration for my mode
AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode);

// gets animation and animations elements
Animation animation = animationMode.getAnimation();

Animations animations = animationMode.getAnimations();

The default values are set in global defaults options, see default global transitions options.

The defaults modes are mapped in the DefaultTransitionKey enumeration and they are:

  • ACTIVE uses the animation configuration when an element is hovering
  • HIDE uses the animation configuration when a dataset is hidden (by using legend or hide method).
  • RESET uses the animation configuration when an element is resetting.
  • RESIZE uses the animation configuration when an element is resizing.
  • SHOW uses the animation configuration when a dataset is shown (by using legend or show method).
// gets animation transitions element
Transitions transitions = chart.getOptions().getTransitions();
// creates an animation transitions configuration for "show"
AnimationTransition animationMode = transitions.create(DefaultTransitionKey.SHOW);
// changes animation configuration setting duration to 10 seconds
animationMode.getAnimation().setDuration(10000);
// updates the chart using "show" mode
chart.update(DefaultTransitionKey.SHOW);

A custom transition can be used by passing it to update or reconfigure methods of the chart.

// creates a custom mode
TransitionKey mode = TransitionKey.create("myMode");
// creates an animation transitions configuration for my mode
AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode);
// changes animation configuration setting duration to 10 seconds
animationMode.getAnimation().setDuration(10000);
// updates the chart using my mode
chart.update(mode);

Disabling animation

To disable an animation configuration, the animation node must be set to false, with the exception for animation transitions which can be disabled by setting the duration to 0.

// ----------------------------------------
// disables all animations
// ----------------------------------------
chart.getOptions().setAnimationEnabled(false);
// ----------------------------------------
// disables animation defined by the collection of 'colors' properties
// ----------------------------------------
chart.getOptions().getAnimations().setEnabled(DefaultAnimationCollectionKey.COLORS, false);
// ----------------------------------------
// disables the animation for 'active' mode
// ----------------------------------------
// gets animation transitions element
Transitions transitions = chart.getOptions().getTransitions();
// creates an animation transitions configuration for "active"
AnimationTransition animationMode = transitions.create(DefaultTransitionKey.ACTIVE);
// changes animation configuration setting duration to 0 seconds
animationMode.getAnimation().setDuration(0);

Events

A chart can emits events during the animation phases, when it's the animation is progressing and completed.

Progressing

The progress event is thrown on each step of an animation. To catch the event and manage it, you can add a AnimationProgressEventHandler instance to the chart options, as following:

chart.addHandler(new AnimationProgressEventHandler(){

/**
* Invoked when chart animation is progressing.
*
* @param event animation event
*/
@Override
public void onProgress(AnimationProgressEvent event){
AnitmationItem item = event.getItem();
// logic
}

}, AnimationProgressEvent.TYPE);

The event provides the animation item object with all information about animation status.

Completed

The complete event is thrown at the end of an animation. To catch the event and manage it, you can add a AnimationCompleteEventHandler instance to the chart options, as following:

chart.addHandler(new AnimationCompleteEventHandler(){

/**
* Invoked when chart animation is complete.
*
* @param event animation event
*/
@Override
public void onComplete(AnimationCompleteEvent event){
AnitmationItem item = event.getItem();
// logic
}

}, AnimationCompleteEvent.TYPE);

The event provides the animation item object with all information about animation status.