animate()

Introduction

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

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

Syntax

animate(keyframes, options);

Parameter

keyframes

There are two different formats:

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,
);

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',
  },
});

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:

Key	Value Type	Optional	Description	Default Value
duration	Number	optional	The length of time for the animation to run.	0
delay	Number	optional	The length of time to wait before starting the animation.	0
iterations	Number	optional	The number of times the animation should repeat. You can set this to `Infinity` to make the animation loop indefinitely.	1
direction	String	optional	Whether 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"`
easing	String	optional	The 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"`
fill	String	optional	Dictates 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"`
name	String	optional	The 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-state	String	optional	Animation motion state, which defines whether an animation is running or paused, accepts an animation-play-state	running

Note:

If no name is specified, a unique id is generated incrementally.
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 Name	Description
`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.

Compatibility

LCD tables only load in the browser

#animate()

#Introduction

#Syntax

#Parameter

#keyframes

#options

#Return Value

#Example

#by getElementById()

#by createSelectorQuery() 3.4

#Multiple animate 3.4

#Animation Event

#Other Infos

#See also

#Compatibility