docs: Update docs and add new animation guide #62874
Open
+412
−28
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
JeanMeche
reviewed
Jul 29, 2025
1bc76a4 to
addec4e
Compare
|
Deployed adev-preview for 64c2b76 to: https://ng-dev-previews-fw--pr-angular-angular-62874-adev-prev-z5std68n.web.app Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt. |
JeanMeche
reviewed
Jul 29, 2025
This adds a guide for enter and leave animations, and updates the prior guides with enter and leave.
addec4e to
64c2b76
Compare
JeanMeche
approved these changes
Jul 29, 2025
jelbourn
reviewed
Jul 29, 2025
|
|
||
| * Without animations, web page transitions can seem abrupt and jarring | ||
| * Motion greatly enhances the user experience, so animations give users a chance to detect the application's response to their actions | ||
| * Good animations intuitively call the user's attention to where it is needed |
There was a problem hiding this comment.
Suggested change
| * Good animations intuitively call the user's attention to where it is needed | |
| * Good animations can smoothly direct the user's attention throughout a workflow |
|
|
||
| ## `animate.enter` | ||
|
|
||
| You can use `animate.enter` to animate elements as they __enter__ the DOM. You can define enter animations using CSS classes with either transforms or keyframe animations. Here's an example: |
There was a problem hiding this comment.
Suggested change
| You can use `animate.enter` to animate elements as they __enter__ the DOM. You can define enter animations using CSS classes with either transforms or keyframe animations. Here's an example: | |
| You can use `animate.enter` to animate elements as they __enter__ the DOM. You can define enter animations using CSS classes with either transforms or keyframe animations: |
IMO the presence of the example implies "Here is an example"
(same comment for other examples)
|
|
||
| You can use `animate.enter` to animate elements as they __enter__ the DOM. You can define enter animations using CSS classes with either transforms or keyframe animations. Here's an example: | ||
|
|
||
| <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.component.ts"> |
There was a problem hiding this comment.
For all of the examples, I would make the height of the container larger so there's not a jump in height when you activate the animation
| <docs-code header="src/app/enter.component.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.component.css"/> | ||
| </docs-code-multifile> | ||
|
|
||
| When the animation completes, Angular removes the class or classes that you specified in `animate.enter` from the DOM. This means they will only be present when the animation is active. |
There was a problem hiding this comment.
Suggested change
| When the animation completes, Angular removes the class or classes that you specified in `animate.enter` from the DOM. This means they will only be present when the animation is active. | |
| When the animation completes, Angular removes the class or classes that you specified in `animate.enter` from the DOM. Animation classes are only be present while the animation is active. |
nit: always present tense (avoid "will")
|
|
||
| When the animation completes, Angular removes the class or classes that you specified in `animate.enter` from the DOM. This means they will only be present when the animation is active. | ||
|
|
||
| NOTE: When using multiple keyframe animations or transition properties on a given element, Angular will wait to remove the classes until the longest of those animations has completed. |
There was a problem hiding this comment.
Suggested change
| NOTE: When using multiple keyframe animations or transition properties on a given element, Angular will wait to remove the classes until the longest of those animations has completed. | |
| NOTE: When using multiple keyframe animations or transition properties on an element, Angular removes all classes only _after_ the longest animation has completed. |
nit: present tense, brevity
(same comment for leave below)
|
|
||
| IMPORTANT: You **must** call the `animationComplete()` function when using `animate.leave`, or Angular will not remove the element. | ||
|
|
||
| If you fail to call `animationComplete()` when using `animate.leave`, Angular calls the function automatically after a four-second timeout. |
There was a problem hiding this comment.
Suggested change
| If you fail to call `animationComplete()` when using `animate.leave`, Angular calls the function automatically after a four-second timeout. | |
| If you don't call `animationComplete()` when using `animate.leave`, Angular calls the function automatically after a four-second delay. |
|
|
||
| ## Testing | ||
|
|
||
| TestBed provides built-in support for enabling or disabling animations in your test environment. CSS animations require a browser to run, and many of the APIs are not available in a test environment. So, by default, TestBed will disable animations for you in your test environments. |
There was a problem hiding this comment.
Suggested change
| TestBed provides built-in support for enabling or disabling animations in your test environment. CSS animations require a browser to run, and many of the APIs are not available in a test environment. So, by default, TestBed will disable animations for you in your test environments. | |
| TestBed provides built-in support for enabling or disabling animations in your test environment. CSS animations require a browser to run, and many of the APIs are not available in a test environment. By default, TestBed disables animations in your test environments. |
|
|
||
| TestBed provides built-in support for enabling or disabling animations in your test environment. CSS animations require a browser to run, and many of the APIs are not available in a test environment. So, by default, TestBed will disable animations for you in your test environments. | ||
|
|
||
| If you would like to test that the animations are animating in a browser test, for example an end-to-end test, you can configure TestBed to enable animations by specifying `animationsEnabled: true` in your test configuration. |
There was a problem hiding this comment.
Suggested change
| If you would like to test that the animations are animating in a browser test, for example an end-to-end test, you can configure TestBed to enable animations by specifying `animationsEnabled: true` in your test configuration. | |
| If you want to test that the animations are animating in a browser test, for example an end-to-end test, you can configure TestBed to enable animations by specifying `animationsEnabled: true` in your test configuration. |
|
|
||
| This will configure animations in your test environment to behave normally. | ||
|
|
||
| NOTE: Some test environments do not announce animation events like `animationstart`, `animationend` and their transition event equivalents. |
| @@ -1,6 +1,6 @@ | |||
| # Migrating away from Angular's Animations package | |||
|
|
|||
| Almost all the features supported by `@angular/animations` have simpler alternatives with native CSS. Consider removing the Angular Animations package from your application, as the package can contribute around 60 kilobytes to your JavaScript bundle. Native CSS animations offer superior performance, as they can benefit from hardware acceleration. Animations defined in the animations package lack that ability. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations. | |||
| The `@angular/animations` package is deprecated as of v20.2, which also introduced the new `animate.enter` and `animate.leave` feature to add animations to your application. Using this new featureset, you can replace all the animations you did with the `@angular/animations` package with pure CSS or even third party animation libraries. Removing `@angular/animations` from your application will cut 60 kilobytes to your JavaScript bundle. Native CSS animations also offer superior performance, as they can benefit from hardware acceleration. Animations defined in the animations package lack that ability. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations. | |||
There was a problem hiding this comment.
Suggested change
| The `@angular/animations` package is deprecated as of v20.2, which also introduced the new `animate.enter` and `animate.leave` feature to add animations to your application. Using this new featureset, you can replace all the animations you did with the `@angular/animations` package with pure CSS or even third party animation libraries. Removing `@angular/animations` from your application will cut 60 kilobytes to your JavaScript bundle. Native CSS animations also offer superior performance, as they can benefit from hardware acceleration. Animations defined in the animations package lack that ability. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations. | |
| The `@angular/animations` package is deprecated as of v20.2, which also introduced the new `animate.enter` and `animate.leave` feature to add animations to your application. Using these new features, you can replace all animations based on `@angular/animations` with plain CSS or JS animation libraries. Removing `@angular/animations` from your application can significantly reduce the size of your JavaScript bundle. Native CSS animations generally offer superior performance, as they can benefit from hardware acceleration. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds a guide for enter and leave animations, and updates the prior guides with enter and leave.