Overview.bs

<h1>CSS Animations Level 2</h1>

<style type="text/css">
  table.play-state-transitions {
    empty-cells: hide;
    border-spacing: 0px;
  }
  table.play-state-transitions td {
    padding: 0.2em 1em;
    border: 1px solid black;
  }
  table.play-state-transitions th.rowgroup {
    transform: rotate(-180deg);
    writing-mode: vertical-lr;
    padding-left: 5px;
  }
</style>

<pre class='metadata'>
Status: ED
Work Status: Exploring
Shortname: css-animations-2
Level: 2
Group: csswg
ED: http://dev.w3.org/csswg/css-animations-2/
Editor: L. David Baron, Mozilla, dbaron@dbaron.org
!Issues List: <a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=Animations&list_id=36653&product=CSS&query_format=advanced&resolution=---">In Bugzilla</a>

Abstract: This CSS module describes a way for authors to animate the values of CSS properties over time, using keyframes. The behavior of these keyframe animations can be controlled by specifying their duration, number of repeats, and repeating behavior.
</pre>
<pre class="anchors">
urlPrefix: https://w3c.github.io/web-animations/; type: method; for: Animation; spec: web-animations
    text: play()
    text: pause()
urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
    text: current time
    text: pause an animation
    text: play an animation
    text: target element
    text: target effect
    text: target effect end
</pre>

<h2 id="delta">Delta specification</h2>

<p>This is a delta specification, meaning that it currently contains
only the differences from CSS Animations Level 1 [[!CSS3-ANIMATIONS]].
Once the Level 1 specification is closer to complete, it will be merged
with the additions here into a complete level 2 specification.</p>

# Animations # {#animations}

## Owning element ## {#owning-element-section}

The <dfn>owning element</dfn> of a CSS Animation refers to the element or
pseudo-element to which the 'animation-name' property was applied that generated
the animation.

If an animation was generated directly by script then it has no <a>owning
element</a>.

If an animation generated using the markup defined in this specification is
later disassociated from that markup by an update to the computed value of the
'animation-name' property on the <a>owning element</a>, the animation is
disassociated from its <a>owning element</a> (that is, it has no <a>owning
element</a> from that point forwards).

<div class="note">

In the example below, <code>animation</code>'s initial <a>owning element</a>
is <code>elem</code>. <code>animation</code> is disassociated from
<code>element</code> through an update to the computed value of
<code>elem</code>'s 'animation-name' property.

<pre class="example lang-javascript">
elem.style.animation = 'spin 1s';
let animation = elem.getAnimations()[0]; // animation's owning element is elem
elem.style.animation = ''; // animation no longer has an owning element
</pre>

Note that although the <a>owning element</a> is often equal to the <a>target
element</a> of an animation's <a>target effect</a>, this is not always the case.
The following example demonstrates some of the situations where these two
elements may differ.

<pre class="example lang-javascript">
elem.style.animation = 'move 1s';
let animation = elem.getAnimations()[0];
// animation.effect.target == elem == animation's owning element

let mutableEffect = animation.effect.clone();
animation.effect = mutableEffect;
animation.effect.target = elem2;
// animation.effect.target == elem2 != animation's owning element

animation.effect = null;
// animation.effect.target is undefined != animation's owning element
</pre>

</div>

# Keyframes # {#keyframes}

## The 'animation-play-state' property ## {#animation-play-state}

### Interaction between 'animation-play-state' and the Web Animations API ### {#interaction-between-animation-play-state-and-web-animations-API}

Both this specification and the Web Animations specification [[WEB-ANIMATIONS]]
define mechanisms for pause control, specifically the 'animation-play-state'
property, and the {{Animation/play()}} and {{Animation/pause()}} methods
respectively.

<div class="note">

The interaction of these methods can be summarized as follows:

*   Calling {{Animation/pause()}} is sticky. The animation will remain paused
    until there is a subsequent call to {{Animation/play()}} after which point
    the animation will begin tracking changes to the computed value of the
    'animation-play-state' property on the <a>owning element</a> from the next
    moment it becomes newly ''paused''.
*   If the computed 'animation-play-state' on the <a>owning element</a> is
    ''paused'', calling {{Animation/play()}} will temporarily override the
    'animation-play-state' until it next becomes ''running''.

</div>

With regards to the pausing, an animation can be considered to be in one of
five mutually-exclusive states:

<ul style="list-style-type: upper-latin">
<li>Running
<li>Running and temporarily overriding 'animation-play-state': ''paused''
<li>Paused and sticky overriding 'animation-play-state': ''running''
<li>Paused and sticky overriding 'animation-play-state': ''paused''
<li>Paused by 'animation-play-state'
</ul>

A state transition chart follows:

<table class="play-state-transitions">
<tr>
  <td rowspan="2"></td>
  <td></td>
  <th colspan="5">Initial state</th>
</tr>
<tr>
  <th>Event</th>
  <th>A</th>
  <th>B</th>
  <th>C</th>
  <th>D</th>
  <th>E</th>
</tr>
<tr>
  <th rowspan="4" class="rowgroup">Resulting state</th>
  <td>{{Animation/play()}}</td>
  <td>A</td>
  <td>B</td>
  <td>A</td>
  <td>B</td>
  <td>B</td>
</tr>
<tr>
  <td>{{Animation/pause()}}</td>
  <td>C</td>
  <td>D</td>
  <td>C</td>
  <td>D</td>
  <td>D</td>
</tr>
<tr>
  <td>'animation-play-state' &rarr; ''running''</td>
  <td>A</td>
  <td>A</td>
  <td>C</td>
  <td>C</td>
  <td>A</td>
</tr>
<tr>
  <td>'animation-play-state' &rarr; ''paused''</td>
  <td>E</td>
  <td>B</td>
  <td>D</td>
  <td>D</td>
  <td>E</td>
</tr>
</table>

If any change causes an animation to change from  one of the running states (A,
B) to one of the paused states (C, D, E), the user agent must run the <a>pause
an animation</a> procedure on the animation.

Likewise, for any change from one of the the paused states to one of the
running states, the user agent must run the <a>play an animation</a> procedure
on the animation. If the change is due to a change in the computed value of
'animation-play-state' (i.e. the transition E &rarr; A) the
<var>auto-rewind</var> flag for that procedure must be set to false; otherwise
it must be set to true.

</div>

# Animation Events # {#events}

## Types of <code>AnimationEvent</code> ## {#event-animationevent}

The <em>additional</em> types of animation events that can occur are:

	<dl dfn-type=event dfn-for=animationevent>
		<dt><dfn>animationcancel</dfn>
		<dd>
			The <a idl>animationcancel</a> event occurs when the animation stops running in a way that does not fire an <a idl>animationend</a> event, such as a change in the 'animation-name' that removes the animation, or the animating element or one of its ancestors becoming ''display:none''.
			<ul>
				<li>Bubbles: Yes</li>
				<li>Cancelable: No</li>
				<li>Context Info: animationName, elapsedTime, pseudoElement</li>
			</ul>
	</dl>