feat(core): add enter and leave animation instructions #62682

thePunderWoman · 2025-07-17T10:18:58Z

This adds the instructions to support enter and leave animations on nodes.

Does this PR introduce a breaking change?

Yes
No

packages/core/src/application/application_tokens.ts

packages/core/src/animation.ts

github-actions · 2025-07-17T11:57:47Z

Deployed adev-preview for 342ed87 to: https://ng-dev-previews-fw--pr-angular-angular-62682-adev-prev-yvy73xs1.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

JeanMeche · 2025-07-17T12:24:54Z

packages/core/src/animation.ts

+  animate(el: Element, removeFn: Function): void {
+    if (!this.outElements.has(el)) return;
+    const details = this.outElements.get(el)!;
+    const timeout = setTimeout(() => removeFn(), 4000);


4000 feels like a magic number here. Can we use a named a named constant and/or have a comment on why this value. (Would animations longer than 4s just get removed after ther 4s ?)

Certainly. I've added a const and associated comment about why 4 seconds.

Also to quickly answer your question here, if you're using an animation function (rather than classes) for animate.leave, you are required to call the complete function to tell the framework when to remove the element. The feedback on the RFC was to have a timeout for safety, and so I went with the same timeout duration as cross document view transitions. So after a 4 second timeout, the element gets removed. If your animation is done before that, no issues.

What if we can have an injection token that configures it? And the default would still be 4s.

We can keep it like this for now, but we should probably output a dev-mode warning for cases when timeout is triggered (for ex. for cases when the "done" callback is never invoked). That can help to surface this situations and we can see if there are cases when the timeout needs to be adjusted.

A couple additional thoughts:

This can be done in a followup PR

We should consider cases when those warnings are produced for elements inside of @for loops and avoid spamming console with those warnings

packages/platform-browser/src/dom/dom_renderer.ts

packages/core/test/acceptance/animation_spec.ts

goldens/public-api/core/index.api.md

packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json

packages/core/src/animation.ts

packages/core/src/render3/instructions/animation.ts

packages/platform-browser/src/dom/dom_renderer.ts

thePunderWoman · 2025-07-18T12:56:36Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for animate.enter and animate.leave instructions for animations on nodes. The changes include new public APIs like AnimationCallbackEvent, AnimationFunction, and ANIMATIONS_DISABLED, a new ElementRegistry service to manage animations for leaving elements, and the core implementation in the rendering instructions. The changes are well-supported by a comprehensive suite of acceptance tests. I've identified a couple of potential issues in packages/core/src/animation.ts and packages/core/src/render3/instructions/animation.ts. Please see my detailed comments.

packages/core/src/animation.ts

packages/core/src/render3/instructions/animation.ts

packages/core/src/errors.ts

packages/core/src/render3/instructions/animation.ts

AndrewKushnir · 2025-07-18T18:34:49Z

packages/core/src/render3/instructions/animation.ts

+  const tNode = getCurrentTNode()!;
+  const nativeElement = getNativeByTNode(tNode, lView) as HTMLElement;
+
+  if ((nativeElement as Node).nodeType !== Node.ELEMENT_NODE) {


Curious what'd be an example of such usage (I believe host bindings might be in that category)? If we come up with an example, we can see what'd be the best way to handle it and whether the code should be at compile-time (preferable, if possible) or at runtime.

AndrewKushnir · 2025-07-18T18:40:46Z

packages/core/src/animation.ts

+  animate(el: Element, removeFn: Function): void {
+    if (!this.outElements.has(el)) return;
+    const details = this.outElements.get(el)!;
+    const timeout = setTimeout(() => removeFn(), 4000);


We can keep it like this for now, but we should probably output a dev-mode warning for cases when timeout is triggered (for ex. for cases when the "done" callback is never invoked). That can help to surface this situations and we can see if there are cases when the timeout needs to be adjusted.

A couple additional thoughts:

This can be done in a followup PR

We should consider cases when those warnings are produced for elements inside of @for loops and avoid spamming console with those warnings

packages/core/src/render3/instructions/animation.ts

packages/core/src/animation.ts

packages/platform-browser/src/dom/dom_renderer.ts

This adds the instructions to support enter and leave animations on nodes.

AndrewKushnir

@thePunderWoman thanks for making the ElementRegistry tree-shakable 👍

I've left a few minor comments and I also wanted to propose that we check whether we can use areAnimationSupported to exit a bit earlier (e.g. in the main instructions vs inside of util functions later).

goldens/public-api/core/index.api.md

packages/core/src/render3/instructions/animation.ts

packages/core/src/render3/state.ts

atscott · 2025-07-22T16:40:34Z

packages/core/src/render3/instructions/animation.ts

+    // The animations will only be disabled in a test environment, and adding a microtask here
+    // will allow the tests to be able to tick forward to resolve the next phase of animation
+    // in their tests.
+    Promise.resolve().then(() => {


I think this should run outside the Angular zone too, right? Unless the intent is to trigger change detection here for applications using NgZone. This would differ from zoneless applications in that case unless we create some trigger for those as well.

This is actually test only. It's intended for people to be able to tick forward in tests and see the classes get added / removed. The token that disables animations is currently in the core/testing package and in a follow up will be only provided in the animations test utility. So it should be ok here.

So to be fair, this will cause tests to behave differently than production (thanks NgZone...) by causing an extra change detection. For better or for worse (definitely for worse), we have observed tests trying to count CD cycles. There could be other cases that this affects as well. For example, the listener callbacks, which execute outside the Angular zone, may make changes to application state. If this isn't done with ngZone.run, markForCheck, etc. production code will not know to trigger change detection but the test code will due to the promise here.

That's always going to be the case, unfortunately. getAnimations does not exist on DOM nodes in a unit test environment. So no animations can actually happen in that case, meaning for those types of tests users have to disable animations. This at least gives them the option to see the classes being added and removed after a tick. So they can verify that the change at least happened. The acceptance tests for this are actually skipping the node environment for that reason.

If you're running tests in a browser, you would not disable animations. So in that case, this code wouldn't be reachable, meaning animations would behave as normal.

AndrewKushnir

LGTM, thanks @thePunderWoman 👍

Just left some minor comments, but none of them are blocking. Let's discuss the testing story as a followup.

goldens/public-api/core/testing/index.api.md

packages/compiler-cli/src/ngtsc/annotations/component/src/animations.ts

packages/core/src/animation.ts

packages/core/src/render3/instructions/animation.ts

AndrewKushnir · 2025-07-22T19:09:07Z

packages/core/src/render3/instructions/animation.ts

+  if (animationsDisabled) {
+    // add a microtask for test environments to be able to see classes
+    // were added, then removed.
+    Promise.resolve().then(() => {
+      finalRemoveFn();
+    });
+  }


Not a blocker for this PR, but we'd probably need to discuss the testing story. I think that relying on the presence of classes may be a bit brittle (especially in case we need to emulate certain timing) and we may instead introduce a utility function to check if a given element was processed by the animation subsystem. That would also allow us to remove this special handling.

packages/platform-browser/src/dom/dom_renderer.ts

This creates a feature to detect usages of animate.leave and only enables the element removal registry when necessary

crisbeto

Reviewed-for: public-api

JeanMeche

reviewed-for: public-api

kirjs · 2025-07-23T13:37:18Z

This PR was merged into the repository by commit 882522c.

The changes were merged into the following branches: main

This creates a feature to detect usages of animate.leave and only enables the element removal registry when necessary PR Close #62682

If `showHideRelatedCards` is refactored into native CSS, then the package `@angular/animations` could be dropped entirely.

thePunderWoman added area: core Issues related to the framework runtime target: minor This PR is targeted for the next minor release labels Jul 17, 2025

ngbot bot added this to the Backlog milestone Jul 17, 2025

angular-robot bot added the detected: feature PR contains a feature commit label Jul 17, 2025

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from 843db01 to 46066a1 Compare July 17, 2025 11:04

pullapprove bot requested review from crisbeto, kirjs and mmalerba July 17, 2025 11:04

thePunderWoman force-pushed the animate-instructions branch from 46066a1 to ba72fa8 Compare July 17, 2025 11:26

JeanMeche reviewed Jul 17, 2025

View reviewed changes

packages/core/src/application/application_tokens.ts Outdated Show resolved Hide resolved

thePunderWoman force-pushed the animate-instructions branch from ba72fa8 to 594389f Compare July 17, 2025 11:38

JeanMeche added the adev: preview label Jul 17, 2025

JeanMeche reviewed Jul 17, 2025

View reviewed changes

packages/core/src/animation.ts Outdated Show resolved Hide resolved

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from 3c38d4a to 056dcb3 Compare July 17, 2025 11:53

JeanMeche reviewed Jul 17, 2025

View reviewed changes

packages/platform-browser/src/dom/dom_renderer.ts Outdated Show resolved Hide resolved

michael-small reviewed Jul 17, 2025

View reviewed changes

packages/core/test/acceptance/animation_spec.ts Outdated Show resolved Hide resolved

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from 72ef660 to 4d2fc63 Compare July 17, 2025 14:34

thePunderWoman added the action: review The PR is still awaiting reviews from at least one requested reviewer label Jul 17, 2025

AndrewKushnir reviewed Jul 17, 2025

View reviewed changes

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from 277e2bf to e6569a6 Compare July 18, 2025 12:25

gemini-code-assist bot reviewed Jul 18, 2025

View reviewed changes

packages/core/src/animation.ts Outdated Show resolved Hide resolved

packages/core/src/animation.ts Outdated Show resolved Hide resolved

packages/core/src/render3/instructions/animation.ts Outdated Show resolved Hide resolved

thePunderWoman force-pushed the animate-instructions branch from e6569a6 to 85f73c2 Compare July 18, 2025 13:42

AndrewKushnir reviewed Jul 18, 2025

View reviewed changes

feat(core): add enter and leave animation instructions

8a926f5

This adds the instructions to support enter and leave animations on nodes.

thePunderWoman force-pushed the animate-instructions branch from 3c026c8 to 8a926f5 Compare July 21, 2025 10:52

angular-robot bot added the area: compiler Issues related to `ngc`, Angular's template compiler label Jul 21, 2025

thePunderWoman force-pushed the animate-instructions branch 3 times, most recently from 9b3ded6 to 45211a4 Compare July 21, 2025 17:39

AndrewKushnir reviewed Jul 22, 2025

View reviewed changes

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from b1822ef to 0d62304 Compare July 22, 2025 10:17

crisbeto approved these changes Jul 22, 2025

View reviewed changes

atscott reviewed Jul 22, 2025

View reviewed changes

pullapprove bot requested a review from atscott July 22, 2025 16:46

thePunderWoman force-pushed the animate-instructions branch 2 times, most recently from 0fb85a4 to 25a89cb Compare July 22, 2025 17:08

AndrewKushnir approved these changes Jul 22, 2025

View reviewed changes

refactor(compiler): Tree shake Element Registry

342ed87

This creates a feature to detect usages of animate.leave and only enables the element removal registry when necessary

thePunderWoman force-pushed the animate-instructions branch from 25a89cb to 342ed87 Compare July 23, 2025 08:36

crisbeto approved these changes Jul 23, 2025

View reviewed changes

JeanMeche approved these changes Jul 23, 2025

View reviewed changes

thePunderWoman removed request for atscott, kirjs and mmalerba July 23, 2025 08:40

thePunderWoman added action: merge The PR is ready for merge by the caretaker and removed action: review The PR is still awaiting reviews from at least one requested reviewer labels Jul 23, 2025

kirjs closed this in 6b1f4b9 Jul 23, 2025

kirjs pushed a commit that referenced this pull request Jul 23, 2025

refactor(compiler): Tree shake Element Registry (#62682)

882522c

This creates a feature to detect usages of animate.leave and only enables the element removal registry when necessary PR Close #62682

PowerKiKi referenced this pull request in unil-lettres/dilps-tiresias Jul 25, 2025

Natural does not require @angular/animations anymore #11561

d6e8e83

If `showHideRelatedCards` is refactored into native CSS, then the package `@angular/animations` could be dropped entirely.

JeanMeche mentioned this pull request Jul 29, 2025

refactor(animations): deprecate the animations package #62795

Closed

feat(core): add enter and leave animation instructions #62682

feat(core): add enter and leave animation instructions #62682

Conversation

thePunderWoman commented Jul 17, 2025

Does this PR introduce a breaking change?

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JeanMeche Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thePunderWoman Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thePunderWoman commented Jul 18, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AndrewKushnir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

atscott Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atscott Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 17, 2025 •

edited

Loading

JeanMeche Jul 17, 2025 •

edited

Loading

thePunderWoman Jul 17, 2025 •

edited

Loading

atscott Jul 22, 2025 •

edited

Loading

atscott Jul 22, 2025 •

edited

Loading