recursal/MDN huggingface dataset:
Animation: startTime property
=============================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`Animation.startTime`** property of the `Animation` interface is a double-precision floating-point value which indicates the scheduled time when an animation's playback should begin.

An animation's **start time** is the time value of its `timeline` when its target `KeyframeEffect` is scheduled to begin playback. An animation's **start time** is initially unresolved (meaning that it's `null` because it has no value).

Value
-----

A floating-point number representing the current time in milliseconds, or `null` if no time is set. You can read this value to determine what the start time is currently set at, and you can change this value to make the animation start at a different time.

Examples
--------

In the Running on Web Animations API example, we can sync all new animated cats by giving them all the same `startTime` as the original running cat:


```js
const catRunning = document
  .getElementById("withWAAPI")
  .animate(keyframes, timing);

/\* A function that makes new cats. \*/
function addCat() {
  const newCat = document.createElement("div");
  newCat.classList.add("cat");
  return newCat;
}

/\* This is the function that adds a cat to the WAAPI column \*/
function animateNewCatWithWAAPI() {
  // make a new cat
  const newCat = addCat();

  // animate said cat with the WAAPI's "animate" function
  const newAnimationPlayer = newCat.animate(keyframes, timing);

  // set the animation's start time to be the same as the original .cat#withWAAPI
  newAnimationPlayer.startTime = catRunning.startTime;

  // Add the cat to the pile.
  WAAPICats.appendChild(newCat);
}
```

Reduced time precision
----------------------

 To offer protection against timing attacks and fingerprinting, the precision of `animation.startTime` might get rounded depending on browser settings.
 In Firefox, the `privacy.reduceTimerPrecision` preference is enabled by default and defaults to 20 µs in Firefox 59; in 60 it will be 2 ms.


```js
// reduced time precision (2ms) in Firefox 60
animation.startTime;
// 23.404
// 24.192
// 25.514
// …

// reduced time precision with `privacy.resistFingerprinting` enabled
animation.startTime;
// 49.8
// 50.6
// 51.7
// …
```


In Firefox, you can also enabled `privacy.resistFingerprinting`, the precision will be 100ms or the value of `privacy.resistFingerprinting.reduceTimerPrecision.microseconds`, whichever is larger.

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-starttime |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation`
* `Animation.currentTime` for the current time of the animation.
Animation: ready property
=========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The read-only **`Animation.ready`** property of the Web Animations API returns a `Promise` which resolves when the animation is ready to play. A new promise is created every time the animation enters the `"pending"` play state as well as when the animation is canceled, since in both of those scenarios, the animation is ready to be started again.

**Note:** Since the same `Promise` is used for both pending `play` and pending `pause` requests, authors are advised to check the state of the animation when the promise is resolved.

Value
-----

A `Promise` which resolves when the animation is ready to be played. You'll typically use a construct similar to this when using the ready promise:


```js
animation.ready.then(() => {
  // Do whatever needs to be done when
  // the animation is ready to run
});
```

Examples
--------

In the following example, the state of the animation will be `running` when the **current ready Promise** is resolved because the animation does not leave the `pending` play state in between the calls to `pause` and `play` and hence the **current ready Promise** does not change.


```js
animation.pause();
animation.ready.then(() => {
  // Displays 'running'
  alert(animation.playState);
});
animation.play();
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-ready |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation`
* `Animation.playState`
Animation: playState property
=============================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The read-only **`Animation.playState`** property of the Web Animations API returns an enumerated value describing the playback state of an animation.

Value
-----

`idle`

The current time of the animation is unresolved and there are no pending tasks.

`running`

The animation is running.

`paused`

The animation was suspended and the `Animation.currentTime` property is not updating.

`finished`

The animation has reached one of its boundaries and the `Animation.currentTime` property is not updating.

Previously, Web Animations defined a **`pending`** value to indicate that some asynchronous operation such as initiating playback was yet to complete. This is now indicated by the separate `Animation.pending` property.

Examples
--------

In the Growing/Shrinking Alice Game example, players can get an ending with Alice crying into a pool of tears. In the game, for performance reasons, the tears should only be animating when they're visible. So they must be paused as soon as they are animated like so:


```js
// Setting up the tear animations

tears.forEach((el) => {
  el.animate(tearsFalling, {
    delay: getRandomMsRange(-1000, 1000), // randomized for each tear
    duration: getRandomMsRange(2000, 6000), // randomized for each tear
    iterations: Infinity,
    easing: "cubic-bezier(0.6, 0.04, 0.98, 0.335)",
  });
  el.pause();
});

// Play the tears falling when the ending needs to be shown.

tears.forEach((el) => {
  el.play();
});

// Reset the crying tears animations and pause them.

tears.forEach((el) => {
  el.pause();
  el.currentTime = 0;
});
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-playstate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation` for other methods and properties you can use to control web page animation.
Animation: playbackRate property
================================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`Animation.playbackRate`** property of the Web Animations API returns or sets the playback rate of the animation.

Animations have a **playback rate** that provides a scaling factor from the rate of change of the animation's `timeline` time values to the animation's current time. The playback rate is initially `1`.

Value
-----

Takes a number that can be 0, negative, or positive. Negative values reverse the animation. The value is a scaling factor, so for example a value of 2 would double the playback rate.

**Note:** Setting an animation's `playbackRate` to `0` effectively pauses the animation (however, its `playstate` does not necessarily become `paused`).

Examples
--------

In the Growing/Shrinking Alice Game example, clicking or tapping the bottle causes Alice's growing animation (`aliceChange`) to reverse, causing her to shrink:


```js
const shrinkAlice = () => {
  aliceChange.playbackRate = -1;
  aliceChange.play();
};

// On tap or click, Alice will shrink.
bottle.addEventListener("mousedown", shrinkAlice, false);
bottle.addEventListener("touchstart", shrinkAlice, false);
```


Contrariwise, clicking on the cake causes her to "grow," playing `aliceChange` forwards again:


```js
const growAlice = () => {
  aliceChange.playbackRate = 1;
  aliceChange.play();
};

// On tap or click, Alice will grow.
cake.addEventListener("mousedown", growAlice, false);
cake.addEventListener("touchstart", growAlice, false);
```


In another example, the Red Queen's Race Game, Alice and the Red Queen are constantly slowing down:


```js
setInterval(() => {
  // Make sure the playback rate never falls below .4

  if (redQueen_alice.playbackRate > 0.4) {
    redQueen_alice.playbackRate \*= 0.9;
  }
}, 3000);
```


But clicking or tapping on them causes them to speed up by multiplying their `playbackRate`:


```js
const goFaster = () => {
  redQueen_alice.playbackRate \*= 1.1;
};

document.addEventListener("click", goFaster);
document.addEventListener("touchstart", goFaster);
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-playbackrate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation`
Animation: updatePlaybackRate() method
======================================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`updatePlaybackRate()`** method of the Web Animations API's
 `Animation` Interface sets the speed of an animation after first
 synchronizing its playback position.

 In some cases, an animation may run on a separate thread or process and will continue
 updating even while long-running JavaScript delays the main thread. In such a case,
 setting the `playbackRate` on the animation
 directly may cause the animation's playback position to jump since its playback
 position on the main thread may have drifted from the playback position where it is
 currently running.

`updatePlaybackRate()` is an asynchronous method that sets the speed of an
 animation after synchronizing with its current playback position, ensuring that the
 resulting change in speed does not produce a sharp jump. After calling
 `updatePlaybackRate()` the animation's `playbackRate` is *not* immediately updated. It will be updated once the
 animation's `ready` promise is resolved.

Syntax
------


```js
updatePlaybackRate(playbackRate)
```

### Parameters

`playbackRate`

 The new speed to set. This may be a positive number (to speed up or slow down
 the animation), a negative number (to make it play backwards), or zero (to
 effectively pause the animation).


### Return value

None (`undefined`).

Examples
--------

 A speed selector component would benefit from smooth updating of
 `updatePlaybackRate()`, as demonstrated below:


```js
speedSelector.addEventListener("input", (evt) => {
  cartoon.updatePlaybackRate(parseFloat(evt.target.value));
  cartoon.ready.then(() => {
    console.log(`Playback rate set to ${cartoon.playbackRate}`);
  });
});
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-updateplaybackrate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation.playbackRate` — read back the current playback rate or set
 it in a synchronous manner.
* `Animation.reverse()` — invert the playback rate and restart playback
 if necessary.
* `Animation` — contains other methods and properties you can use to
 control web page animation.
Animation: effect property
==========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`Animation.effect`** property of the Web Animations API gets and sets the target effect of an animation. The target effect may be either an effect object of a type based on `AnimationEffect`, such as `KeyframeEffect`, or `null`.

Value
-----

A `AnimationEffect` object describing the target animation effect for the animation, or `null` to indicate no active effect.

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-effect |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `AnimationEffect`
* `Animation`
Animation: play() method
========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`play()`** method of the Web Animations API's `Animation` Interface starts or resumes playing of an animation. If the animation is finished, calling `play()` restarts the animation, playing it from the beginning.

Syntax
------


```js
play()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

In the Growing/Shrinking Alice Game example, clicking or tapping the cake causes Alice's growing animation (`aliceChange`) to play forward, causing her to get bigger, as well as triggering the cake's animation. Two `Animation.play()`s, one `EventListener`:


```js
// The cake has its own animation:
const nommingCake = document
  .getElementById("eat-me\_sprite")
  .animate(
    [{ transform: "translateY(0)" }, { transform: "translateY(-80%)" }],
    {
      fill: "forwards",
      easing: "steps(4, end)",
      duration: aliceChange.effect.timing.duration / 2,
    },
  );

// Pause the cake's animation so it doesn't play immediately.
nommingCake.pause();

// This function will play when ever a user clicks or taps
const growAlice = () => {
  // Play Alice's animation.
  aliceChange.play();

  // Play the cake's animation.
  nommingCake.play();
};

// When a user holds their mouse down or taps, call growAlice to make all the animations play.
cake.addEventListener("mousedown", growAlice, false);
cake.addEventListener("touchstart", growAlice, false);
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-play |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation` for other methods and properties you can use to control web page animation.
* `Animation.pause()` to pause an animation.
* `Animation.reverse()` to play an animation backwards.
* `Animation.finish()` to finish an animation.
* `Animation.cancel()` to cancel an animation.
Animation: pending property
===========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The read-only **`Animation.pending`** property of the Web Animations API indicates whether the animation is currently waiting for an asynchronous operation such as initiating playback or pausing a running animation.

Value
-----

**`true`** if the animation is pending, **`false`** otherwise.

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-pending |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Animation` for other methods and properties you can use to control web page animation.
* Web Animations API
Animation: currentTime property
===============================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`Animation.currentTime`** property of the Web Animations API returns and sets the current time value of the animation in milliseconds, whether running or paused.

If the animation lacks a `timeline`, is inactive, or hasn't been played yet, `currentTime`'s return value is `null`.

Value
-----

A number representing the current time in milliseconds, or `null` to deactivate the animation.

Examples
--------

In the Drink Me/Eat Me game, Alice's height is animated so it can go from small to large or large to small. At the start of the game, her height is set between the two extremes by setting her animation's `currentTime` to half her `KeyframeEffect`'s duration:


```js
aliceChange.currentTime = aliceChange.effect.timing.duration / 2;
```


A more generic means of seeking to the 50% mark of an animation would be:


```js
animation.currentTime =
  animation.effect.getComputedTiming().delay +
  animation.effect.getComputedTiming().activeDuration / 2;
```

Reduced time precision
----------------------

 To offer protection against timing attacks and fingerprinting, the precision of `animation.currentTime` might get rounded depending on browser settings.
 In Firefox, the `privacy.reduceTimerPrecision` preference is enabled by default and defaults to 20 microseconds in Firefox 59; in 60 it will be 2 milliseconds.


```js
// reduced time precision (2ms) in Firefox 60
animation.currentTime;
// 23.404
// 24.192
// 25.514
// …

// reduced time precision with `privacy.resistFingerprinting` enabled
animation.currentTime;
// 49.8
// 50.6
// 51.7
// …
```


In Firefox, you can also enabled `privacy.resistFingerprinting`, the precision will be 100ms or the value of `privacy.resistFingerprinting.reduceTimerPrecision.microseconds`, whichever is larger.

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-currenttime |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Animation` for other methods and properties you can use to control web page animation.
* `Animation.startTime` for the time an animation is scheduled to start.
* Web Animations API
Animation: timeline property
============================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`Animation.timeline`** property of the `Animation` interface returns or sets the `timeline` associated with this animation. A timeline is a source of time values for synchronization purposes, and is an `AnimationTimeline`-based object. By default, the animation's timeline and the `Document`'s timeline are the same.

Value
-----

A timeline object to use as the timing source for the animation, or `null` to use the default, which is the `Document`'s timeline.

Examples
--------

Here we set the animation's timeline to be the same as the document's timeline (this is the default timeline for all animations, by the way):


```js
animation.timeline = document.timeline;
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-timeline |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation`
* `AnimationTimeline` the parent object all timelines inherit from.
* `DocumentTimeline` the only kind of timeline object available at this time.
* `Document.timeline` is the default timeline all animations are assigned.
Animation: replaceState property
================================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The read-only **`Animation.replaceState`** property of the Web Animations API indicates whether the animation has been removed by the browser automatically after being replaced by another animation.

Value
-----

A string that represents the replace state of the animation. The value can be one of:

`active`

The initial value of the animation's replace state when the animation is created.

`persisted`

The animation has been explicitly persisted by invoking `Animation.persist()` on it.

`removed`

The animation has been removed by the browser automatically.

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-replacestate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation`
* `remove` event
* `Animation.persist()`
Animation: pause() method
=========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`pause()`** method of the Web Animations API's `Animation` interface suspends playback of the animation.

Syntax
------


```js
animation.pause();
```

### Parameters

None.

### Return value

None.

### Exceptions

`InvalidStateError` `DOMException`

Thrown if the animation's `currentTime` is `unresolved` (perhaps it hasn't started playing yet), and the end time of the animation is positive infinity.

Example
-------

`Animation.pause()` is used many times in the Alice in Web Animations API Land Growing/Shrinking Alice Game, largely because animations created with the `Element.animate()` method immediately start playing and must be paused manually if you want to avoid that:


```js
// animation of the cupcake slowly getting eaten up
const nommingCake = document
  .getElementById("eat-me\_sprite")
  .animate(
    [{ transform: "translateY(0)" }, { transform: "translateY(-80%)" }],
    {
      fill: "forwards",
      easing: "steps(4, end)",
      duration: aliceChange.effect.timing.duration / 2,
    },
  );

// doesn't actually need to be eaten until a click event, so pause it initially:
nommingCake.pause();
```


Additionally, when resetting:


```js
// An all-purpose function to pause the animations on Alice, the cupcake, and the bottle that reads "drink me."
const stopPlayingAlice = () => {
  aliceChange.pause();
  nommingCake.pause();
  drinking.pause();
};

// When the user releases the cupcake or the bottle, pause the animations.
cake.addEventListener("mouseup", stopPlayingAlice, false);
bottle.addEventListener("mouseup", stopPlayingAlice, false);
```

Specifications
--------------

| Specification |
| --- |
| Web Animations # dom-animation-pause |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Animations API
* `Animation` for other methods and properties you can use to control web page animation.
* `Animation.pause()` to pause an animation.
* `Animation.reverse()` to play an animation backwards.
* `Animation.finish()` to finish an animation.
* `Animation.cancel()` to cancel an animation.