@angular/animations

query

function

deprecatedsince v20.2

Finds one or more inner elements within the current element that is being animated within a sequence. Use with animate().

Deprecation warning

Use animate.enter or animate.leave instead. Intent to remove in v23

API

function query(
  selector: string,
  animation: AnimationMetadata | AnimationMetadata[],
  options?: AnimationQueryOptions | null,
): AnimationQueryMetadata;

@deprecated

Use animate.enter or animate.leave instead. Intent to remove in v23

@paramselectorstring

The element to query, or a set of elements that contain Angular-specific characteristics, specified with one or more of the following tokens.

query(":enter") or query(":leave") : Query for newly inserted/removed elements (not all elements can be queried via these tokens, see Entering and Leaving Elements)
query(":animating") : Query all currently animating elements.
query("@triggerName") : Query elements that contain an animation trigger.
query("@*") : Query all elements that contain an animation triggers.
query(":self") : Include the current element into the animation sequence.

@paramanimationAnimationMetadata | AnimationMetadata[]

One or more animation steps to apply to the queried element or elements. An array is treated as an animation sequence.

@paramoptionsAnimationQueryOptions | null

An options object. Use the 'limit' field to limit the total number of items to collect.

@returnsAnimationQueryMetadata

Usage Notes

Multiple Tokens

Tokens can be merged into a combined query selector string. For example:

query('@subTrigger, :self, .record:enter, .record:leave', [...])

The query() function collects multiple elements and works internally by using element.querySelectorAll. Use the limit field of an options object to limit the total number of items to be collected. For example:

query('div', [
  animate(...),
  animate(...)
], { limit: 1 })

By default, throws an error when zero items are found. Set the optional flag to ignore this error. For example:

query('.some-element-that-may-not-be-there', [
  animate(...),
  animate(...)
], { optional: true })

Entering and Leaving Elements

Not all elements can be queried via the :enter and :leave tokens, the only ones that can are those that Angular assumes can enter/leave based on their own logic (if their insertion/removal is simply a consequence of that of their parent they should be queried via a different token in their parent's :enter/:leave transitions).

The only elements Angular assumes can enter/leave based on their own logic (thus the only ones that can be queried via the :enter and :leave tokens) are:

Those inserted dynamically (via ViewContainerRef)
Those that have a structural directive (which, under the hood, are a subset of the above ones)

Note that elements will be successfully queried via :enter/:leave even if their insertion/removal is not done manually via ViewContainerRefor caused by their structural directive (e.g. they enter/exit alongside their parent).

There is an exception to what previously mentioned, besides elements entering/leaving based on their own logic, elements with an animation trigger can always be queried via :leave when their parent is also leaving.

Usage Example

The following example queries for inner elements and animates them individually using animate().

@Component({
  selector: 'inner',
  template: `
    <div [@queryAnimation]="exp">
      <h1>Title</h1>
      <div class="content">
        Blah blah blah
      </div>
    </div>
  `,
  animations: [
   trigger('queryAnimation', [
     transition('* => goAnimate', [
       // hide the inner elements
       query('h1', style({ opacity: 0 })),
       query('.content', style({ opacity: 0 })),

       // animate the inner elements in, one by one
       query('h1', animate(1000, style({ opacity: 1 }))),
       query('.content', animate(1000, style({ opacity: 1 }))),
     ])
   ])
 ]
})
class Cmp {
  exp = '';

  goAnimate() {
    this.exp = 'goAnimate';
  }
}