CKTIS / JavaScript
Animation.finished — the animation completion promise
Animation.finished lets you await animation completion while accounting for cancellation.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const completedAnimation = await animation.finished;Animation.finished is a read-only property returning a Promise<Animation>. When the animation reaches finished, including through finish(), the promise can fulfill with the animation object. It is neither a boolean nor a method.
Leaving finished replaces the current promise only if it has already fulfilled. If the animation leaves that state before a queued finish notification fulfills the promise, the same promise can remain pending. Read the property again for another playback. If the animation is not idle, cancel() rejects its current finished promise with a DOMException named AbortError if the promise is still pending. Use try/catch to handle that rejection. If the animation is already idle, cancel() leaves a pending finished promise pending, so await can remain suspended without entering the catch block. ready indicates playback or pause readiness, not animation completion.
This is Web Animations, not ECMAScript. Browser support is required; Node 24 in the repository does not establish it.
Examples
(async () => {
const element = document.createElement('div');
element.textContent = 'Animation.finished';
document.body.append(element);
const animation = element.animate(
[{ opacity: 0 }, { opacity: 1 }],
{ duration: 1000, fill: 'forwards' }
);
try {
const completion = animation.finished;
animation.finish();
const result = await completion;
console.log(result === animation);
console.log(animation.playState);
} catch (error) {
console.log(error.name);
} finally {
animation.cancel();
element.remove();
}
})();Result
true finished
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.