From 299607d0fb7a685aa6d15d0f64d58e8fd294fb9e Mon Sep 17 00:00:00 2001 From: Jessica Janiuk Date: Tue, 11 Aug 2026 15:32:19 -0700 Subject: [PATCH] docs: clarify animate.leave child animation behavior This updates the docs to be explicit about `animate.leave` and nested element removal order. It clearly specifies that `animate.leave` will only fire nested animations within the same component template. closes: #70131 (cherry picked from commit 3d32db6a493e24c09da9bff6f01c7a73ae804f44) --- adev/src/content/guide/animations/css.md | 2 ++ adev/src/content/guide/animations/enter-and-leave.md | 4 +++- adev/src/content/guide/animations/migration.md | 2 ++ 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/adev/src/content/guide/animations/css.md b/adev/src/content/guide/animations/css.md index 30e4c802d41..41267bd8a7d 100644 --- a/adev/src/content/guide/animations/css.md +++ b/adev/src/content/guide/animations/css.md @@ -90,6 +90,8 @@ Animating an element when it leaves the view is similar to animating when enteri +NOTE: Child `animate.leave` animations fire only within the same component template. Nested component `animate.leave` animations will not fire when a parent element is removed. + For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations). ### Animating increment and decrement diff --git a/adev/src/content/guide/animations/enter-and-leave.md b/adev/src/content/guide/animations/enter-and-leave.md index 7817950ed91..01397e2aa3c 100644 --- a/adev/src/content/guide/animations/enter-and-leave.md +++ b/adev/src/content/guide/animations/enter-and-leave.md @@ -57,7 +57,7 @@ NOTE: When using multiple keyframe animations or transition properties on an ele ### Element removal order -There is some nuance to how `animate.leave` animations are run and when an animation will occur. `animate.leave` works if it is placed on the element that is being removed, and if `animate.leave` is placed on an element that is a _descendent_ of the element being removed, those child animations will happen _before_ the parent node is removed from the DOM. This ensures that you can confidently animate away child elements without the parent node disappearing prematurely. +There is some nuance to how `animate.leave` animations are run and when an animation will occur. `animate.leave` works if it is placed on the element that is being removed, and if `animate.leave` is placed on an element that is a _descendant_ of the element being removed _within the same component template_, those child `animate.leave` animations will happen _before_ the parent node is removed from the DOM. This ensures that you can confidently animate away child elements without the parent node disappearing prematurely. @@ -65,6 +65,8 @@ There is some nuance to how `animate.leave` animations are run and when an anima +IMPORTANT: Child animations fire only for elements within the same component template. If an element being removed contains child components, any `animate.leave` animations defined inside those child component templates will **not** run before the parent is removed. To animate a child component on removal, apply `animate.leave` to the child component's host element directly within the parent template instead, or programmatically handle triggering the animation in the child component and delaying the removal of the parent until that animation completes. + ## Event Bindings, Functions, and Third-party Libraries Both `animate.enter` and `animate.leave` support event binding syntax that allows for function calls. You can use this syntax to call a function in your component code or utilize third-party animation libraries, like [GSAP](https://gsap.com/), [anime.js](https://animejs.com/), or any other JavaScript animation library. diff --git a/adev/src/content/guide/animations/migration.md b/adev/src/content/guide/animations/migration.md index 32a960290d2..fefe8097367 100644 --- a/adev/src/content/guide/animations/migration.md +++ b/adev/src/content/guide/animations/migration.md @@ -168,6 +168,8 @@ Along with the aforementioned `:enter` and `:leave`, there's also `:increment` a Unlike the animations package, when multiple animations are specified within a given component, no animation has priority over another and nothing blocks any animation from firing. Any sequencing of animations would have to be handled by your definition of your CSS animation, using animation / transition delay, and / or using `animationend` or `transitionend` to handle adding the next css to be animated. +Child animations fire only within the same component template. In the `@angular/animations` package, parent animations could query and trigger animations in nested child components using `query()` and `animateChild()`. With `animate.leave` and native CSS animations, animations defined inside nested child component templates will not fire when a parent component removes an element or view. Only nested animations within the same Angular component template will execute. See the [Enter and Leave Animations guide](guide/animations#element-removal-order) for more information on this. + ### Disabling an animation or all animations With native CSS animations, if you'd like to disable the animations that you've specified, you have multiple options.