You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `commitStyles()` method of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("Animation")}} interface writes the [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute.`commitStyles()` works even if the animation has been [automatically removed](/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API#automatically_removing_filling_animations).
11
+
The `commitStyles()` method of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("Animation")}} interface writes the [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute.
12
12
13
-
`commitStyles()` can be used in combination with `fill` to cause the final state of an animation to persist after the animation ends. The same effect could be achieved with `fill` alone, but [using indefinitely filling animations is discouraged](https://drafts.csswg.org/web-animations-1/#fill-behavior). Animations [take precedence over all static styles](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order), so an indefinite filling animation can prevent the target element from ever being styled normally.
14
-
15
-
Using `commitStyles()` writes the styling state into the element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, where they can be modified and replaced as normal.
13
+
It is primarily used to write the styles for the final state of an animation into the target element, so that the styling persists after the animation ends.
16
14
17
15
## Syntax
18
16
@@ -28,68 +26,188 @@ None.
28
26
29
27
None ({{jsxref("undefined")}}).
30
28
29
+
## Description
30
+
31
+
The `commitStyles()` method is primarily used to write the [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) for the final state of an animation into the target element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, so that the styling persists after the animation ends.
32
+
This can be done when the animation has finished (that is, the {{domxref("Animation")}} object's {{domxref("Animation.finished","finished")}} property has resolved).
33
+
34
+
### `commitStyles()` alongside fill mode
35
+
36
+
On older browsers, you must specify the [`fill` mode](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#fill) in order to be able to commit the styles to the element _after_ the animation has finished.
37
+
38
+
The code below shows how you can animate an element named `animatedElement`, setting [`fill: "forwards"`](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#fill) to persist the animation styles after it finishes.
39
+
Once the animation is finished we commit the styles to the element with `commitStyles()`.
40
+
41
+
```js
42
+
// Start the animation
43
+
constanimation=animatedElement.animate(
44
+
{ transform:"translate(100px)" },
45
+
{ duration:500, fill:"forwards" },
46
+
);
47
+
48
+
// Wait for the animation to finish
49
+
awaitanimation.finished;
50
+
// Commit animation state to he animatedElement style attribute
51
+
animation.commitStyles();
52
+
// Cancel the animation
53
+
animation.cancel();
54
+
```
55
+
56
+
As `fill` persists the animation indefinitely, once we've committed the styles, we cancel the animation.
57
+
58
+
Note that the same effect could be achieved with `fill` alone, but [using indefinitely filling animations is discouraged](https://drafts.csswg.org/web-animations-1/#fill-behavior).
59
+
Animations [take precedence over all static styles](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order), so an indefinite filling animation can prevent the target element from ever being styled normally.
60
+
61
+
> [!NOTE]
62
+
> You might also avoid having to explicitly save the final state by setting them as the element initial styles and animating to the final styles.
63
+
64
+
### `commitStyles()` without setting fill mode
65
+
66
+
In newer browsers you do not need to set the [`fill` mode](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#fill) (see the [browser compatibility table](#browser_compatibility) for specific versions).
67
+
68
+
> [!NOTE]
69
+
> There is no way to feature check for this new behaviour.
70
+
> For now most code should continue to set `fill` as shown in the previous section.
71
+
72
+
The code below shows how you can animate an element named `animatedElement`, wait on the animation to complete using the {{domxref("Animation.finished","finished")}} property, and then commit the styles to the element with `commitStyles()`.
73
+
Because we're not setting `fill` we don't have to cancel the animation afterwards.
74
+
75
+
```js
76
+
// Start the animation
77
+
constanimation=animatedElement.animate(
78
+
{ transform:"translate(100px)" },
79
+
{ duration:500 },
80
+
);
81
+
82
+
// Wait for the animation to finish
83
+
awaitanimation.finished;
84
+
85
+
// Commit animation state to the animatedElement style attribute
86
+
animation.commitStyles();
87
+
```
88
+
89
+
`commitStyles()` works even if the animation has been [automatically removed](/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API#automatically_removing_filling_animations).
90
+
After the element's styles have been committed they can be modified and replaced as normal.
91
+
31
92
## Examples
32
93
33
-
### Committing the final state of an animation
94
+
### Animation with and without using fill
34
95
35
-
In this example we have two buttons, labeled "Commit styles" and "Fill forwards". Both buttons animate when you click them, and both buttons persist the final state of the animation.
96
+
This example demonstrates how you can use `commitStyles()` to save the computed styles at the end of the animation, both with and without using `fill`.
97
+
It also provides an example of what happens if neither `commitStyles()` or `fill` are used, for comparison.
36
98
37
-
The difference, though, is that "Fill forwards" only uses `fill: "forwards"` to persist the animation's final state: this means that the browser has to maintain the animation's state indefinitely, or until it can be automatically removed.
99
+
The example first displays two buttons labelled "commitStyles() only" and "commitStyles() with fill".
100
+
Both buttons animate when you click them, and both buttons call `commitStyles()` to persist the final state of the animation.
101
+
The difference is that "commitStyles() only" does not specify `fill: "forwards"` to persist the animation's final state.
102
+
On browsers that don't match the current specification the final state may not be captured.
38
103
39
-
However, the "Commit styles" button waits for the animation to finish, then calls `commitStyles()`, then cancels the animation, so the finished style is captured as the value of the `style` attribute, rather than as the animation state.
104
+
The code then displays a button "No commitStyles() or fill" that can be used for comparison, and a "Reset" button.
Note that the first button will "jump" at the end of the animation if the current browser still requires `fill` for styles to be committed after the end of the animation.
208
+
The "No commitStyles() or fill" button always jumps at the end, because the final state is not saved.
209
+
210
+
{{EmbedLiveSample("Animation with and without using fill")}}
0 commit comments