+
+ `,
+ styleUrls: ['./querying.component.css'],
+ animations: [
+ trigger('query', [
+ transition(':enter', [
+ style({ height: 0 }),
+ group([
+ animate(500, style({ height: '*' })),
+ query(':enter', [
+ style({ opacity: 0, transform: 'scale(0)'}),
+ animate(2000, style({ opacity: 1, transform: 'scale(1)' }))
+ ]),
+ query('.hero', [
+ style({ transform: 'translateX(-100%)'}),
+ animate('.7s 500ms ease-in', style({ transform: 'translateX(0)' }))
+ ]),
+ ]),
+ query('@animateMe', animateChild()),
+ ]),
+ transition(':leave', [
+ style({ height: '*' }),
+ query('@animateMe', animateChild()),
+ group([
+ animate('500ms 500ms', style({ height: '0', padding: '0' })),
+ query(':leave', [
+ style({ opacity: 1, transform: 'scale(1)'}),
+ animate('1s', style({ opacity: 0, transform: 'scale(0)' }))
+ ]),
+ query('.hero', [
+ style({ transform: 'translateX(0)'}),
+ animate('.7s ease-out', style({ transform: 'translateX(-100%)' }))
+ ]),
+ ]),
+ ]),
+ ]),
+ trigger('animateMe', [
+ transition('* <=> *', animate('500ms cubic-bezier(.68,-0.73,.26,1.65)', keyframes([
+ style({ backgroundColor: "transparent", color: '*', offset: 0 }),
+ style({ backgroundColor: "blue", color: 'white', offset: 0.2 }),
+ style({ backgroundColor: "transparent", color: '*', offset: 1 })
+ ])))
+ ]),
+ ]
+})
+export class QueryingComponent {
+ toggleDisabled = false;
+ show = true;
+ hero = HEROES[0];
+}
diff --git a/aio/content/guide/complex-animation-sequences.md b/aio/content/guide/complex-animation-sequences.md
index aeb9256eb69..eee10fad75b 100644
--- a/aio/content/guide/complex-animation-sequences.md
+++ b/aio/content/guide/complex-animation-sequences.md
@@ -20,11 +20,34 @@ The functions that control complex animation sequences are:
{@a complex-sequence}
+## The query() function
+
+Most complex animations rely on the `query()` function to find child elements and apply animations to them, basic examples of such are:
+ - `query()` followed by `animate()`
+ used to query simple HTML elements and directly apply animations to them.
+ - `query()` followed by `animateChild()`
+ used to query child elements which themselves have animations metadata applied to them and trigger such animation (which would be otherwise be blocked by the current/parent element's animation)
+
+The first argument of `query()` is a [css selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) string which can also contain the following angular-specific tokens:
+ - `:enter`/`:leave` for entering/leaving elements
+ - `:animating` for elements currently animating
+ - `@*`/`@triggerName` for elements with any or a specific trigger
+ - `:self` the animating element itself
+
+
+
+ Entering and Leaving Elements
+
+ Not all child elements are actually considered as entering/leaving, this can at times be counterintuitive and confusing, please see the [query api docs](/api/animations/query#entering-and-leaving-elements) for more information.
+
+
+ You can also see an illustration of this in the animations live example (introduced in the animations [introduction section](/guide/animations#about-this-guide)) under the Querying tab.
+
+
+
## Animate multiple elements using query() and stagger() functions
-The `query()` function lets you find inner elements within the element that is being animated. This function targets specific HTML elements within a parent component and applies animations to each element individually. Angular intelligently handles setup, teardown, and cleanup as it coordinates the elements across the page.
-
-The `stagger()` function lets you define a timing gap between each queried item that is animated and thus animates elements with a delay between them.
+After having queried child elements via `query()`, the `stagger()` function lets you define a timing gap between each queried item that is animated and thus animates elements with a delay between them.
The following example demonstrates how to use the `query()` and `stagger()` functions to animate a list (of heroes) adding each in sequence, with a slight delay, from top to bottom.
diff --git a/aio/content/guide/transition-and-triggers.md b/aio/content/guide/transition-and-triggers.md
index 45869ee1a74..1b37927bb32 100644
--- a/aio/content/guide/transition-and-triggers.md
+++ b/aio/content/guide/transition-and-triggers.md
@@ -75,12 +75,6 @@ Combine wildcard and void states in a transition to trigger animations that ente
This section shows how to animate elements entering or leaving a page.
-
-
-**Note:** For this example, an element entering or leaving a view is equivalent to being inserted or removed from the DOM.
-
-
-
Add a new behavior:
* When you add a hero to the list of heroes, it appears to fly onto the page from the left.
@@ -109,6 +103,12 @@ So, use the aliases `:enter` and `:leave` to target HTML elements that are inser
The `:enter` transition runs when any `*ngIf` or `*ngFor` views are placed on the page, and `:leave` runs when those views are removed from the page.
+
+
+ **Note:** Entering/leaving behaviors can sometime be confusing. As a rule of thumb consider that any element being added to the DOM by Angular passes via the `:enter` transition, but only elements being directly removed from the DOM by Angular pass via the `:leave` transition (e.g. an element's view is removed from the DOM because its parent is being removed from the DOM or the app's route has changed, then the element will not pass via the `:leave` transition).
+
+
+
This example has a special trigger for the enter and leave animation called `myInsertRemoveTrigger`. The HTML template contains the following code.