Lynx
Guide
APIs
Blog
Contribute
Guide
APIs
Blog
Contribute

animate()

Introduction

Use animate() to set a CSS Animation on UI elements.

  1. Use the getElementById API to find the Element object that needs to be animated based on its id.
  2. Call the animate API on the Element object to achieve animation.

Syntax

animate(keyframes, options);

Parameter

keyframes

There are two different formats:

  1. An array consisting of objects that contain properties and values of multiple keyframes.
element.animate(
  [
    {
      // from
      opacity: 0,
      color: '#fff',
    },
    {
      // to
      opacity: 1,
      color: '#000',
    },
  ],
  2000,
);
  1. An object consisting of keys as offsets and values as keyframes.
element.animate({
  '0%': {
    // from
    opacity: 0,
    color: '#fff',
  },
  '50%': {
    // 50%
    opacity: 0.5,
    color: '#aaa',
  },
  '100%': {
    // to
    opacity: 1,
    color: '#000',
  },
});
  1. You can also assign a timing-function for each keyframe.
element.animate([
  {
    // from
    opacity: 0,
    color: '#fff',
    'animation-timing-function': 'linear',
  },
  {
    // to
    opacity: 1,
    color: '#000',
    'animation-timing-function': 'ease-in',
  },
]);

options

An object that contains one or more properties:

KeyValue TypeOptionalDescriptionDefault Value
durationNumberoptionalThe length of time for the animation to run.0
delayNumberoptionalThe length of time to wait before starting the animation.0
iterationsNumberoptionalThe number of times the animation should repeat. You can set this to Infinity to make the animation loop indefinitely.1
directionStringoptionalWhether the animation runs forwards (normal), backwards (reverse), switches direction after each iteration (alternate), or runs backwards and switches direction after each iteration (alternate-reverse). Defaults to "normal"."normal"
easingStringoptionalThe rate of the animation's change over time. Accepts an timing-function, such as "linear", "ease-in", or "cubic-bezier(0.42, 0, 0.58, 1)". Defaults to "linear"."linear"
fillStringoptionalDictates whether the animation's effects should be reflected by the element(s) prior to playing ("backwards"), retained after the animation has completed playing ("forwards"), or both. Defaults to "none"."none"
nameStringoptionalThe name of the animation, which can be used to uniquely identify it. This name appears in the animation events parameters and is typically used to determine if a particular animation event is the one you're interested in.An internal unique ID.
play-stateStringoptionalAnimation motion state, which defines whether an animation is running or paused, accepts an animation-play-staterunning
Note:
  1. If no name is specified, a unique id is generated incrementally.
  2. An animation with the same name cannot be triggered consecutively multiple times.

Return Value

Returns an Animation object. The Animation object has the following methods:

Method NameDescription
Animation.cancel()Cancels the animation and triggers the animation cancel event.
Animation.pause()Pauses the animation.
Animation.play()Resumes the animation.

Example

by getElementById()

let ani = lynx.getElementById('test').animate(
  [
    {
      'background-color': 'blue',
      transform: 'translateX(100px) translateY(300px) rotate(360deg)',
    },
    {
      'background-color': 'red',
      transform: 'translateX(0px) translateY(600px) rotate(0deg)',
    },
  ],
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

// When the parameter is Object, it is strictly required to write percentages with a percent sign such as '.50' and '50' equivalents are divided by 100
let ani = lynx.getElementById('test').animate(
  {
    '0%': {
      transform: 'rotate(0deg)',
      left: '0px',
    },
    '50%': {
      // The properties of the intermediate frame can default.
      left: '30px',
    },
    '100%': {
      transform: 'rotate(225deg)',
      left: '100px',
    },
  },
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

ani.pause();
ani.play();
ani.cancel();
NOTE
  • Each call to getElementById("test").animate will generate a new Animation object, and the later created animation will override the previous ones.
  • If you want to restart the same animation, you need to call getElementById("test").animate again to create a new Animation object.

by createSelectorQuery()
3.4

After Lynx version 3.4, the animate() can be called via the createSelectorQuery().

It's an experimental feature, and you should use it with caution.

const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1'])
  .exec();

Multiple animate
3.4

After Lynx version 3.4, you can chain multiple animation with createSelectorQuery().

It's an experimental feature, and you should use it with caution.

const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

const ani2 = lynx.createAnimation(
  'ani2',
  [
    {
      'background-color': 'red',
    },
    {
      'background-color': 'blue',
    },
  ],
  {
    name: 'js-animation-2',
    duration: 3000,
    easing: 'linear',
    fill: 'forwards',
    iterations: 'infinite',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1, ani2]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1', 'js-animation-2'])
  .exec();

Animation Event

The events for the animate() API are the same as the animation events for CSS animations.

Other Infos

TIP

  • Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.

  • The Animate API may not take effect, possibly because getElementById failed to select the node:

    • The ID selector might be incorrect
    • The value of the ID selector might depend on a complex JS expression, causing the value of the ID selector not to be available on the first screen. In this case, if getElementById is invoked too early (like in ComponentDidMount), it might not find the node.

See also

Compatibility

LCD tables only load in the browser

Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.