• Overview
@angular/core

ViewChildren

decorator

Property decorator that configures a view query.

API

@ViewChildren(
  selector: ProviderToken<unknown> | Function | string,
  opts?: { read?: any; emitDistinctChangesOnly?: boolean },
);

Description

Property decorator that configures a view query.

Use to get the QueryList of elements or directives from the view DOM. Any time a child element is added, removed, or moved, the query list will be updated, and the changes observable of the query list will emit a new value.

View queries are set before the ngAfterViewInit callback is called.

Metadata Properties:

  • selector - The directive type or the name used for querying.
  • read - Used to read a different token from the queried elements.
  • emitDistinctChangesOnly - The QueryList#changes observable will emit new values only if the QueryList result has changed. When false the changes observable might emit even if the QueryList has not changed. ** Note: *** This config option is deprecated, it will be permanently set to true and removed in future versions of Angular.

The following selectors are supported.

  • Any class with the @Component or @Directive decorator
  • A template reference variable as a string (e.g. query <my-component #cmp></my-component> with @ViewChildren('cmp'))
  • Any provider defined in the child component tree of the current component (e.g. @ViewChildren(SomeService) someService!: SomeService)
  • Any provider defined through a string token (e.g. @ViewChildren('someToken') someTokenVal!: any)
  • A TemplateRef (e.g. query <ng-template></ng-template> with @ViewChildren(TemplateRef) template;)

In addition, multiple string selectors can be separated with a comma (e.g. @ViewChildren('cmp1,cmp2'))

The following values are supported by read:

  • Any class with the @Component or @Directive decorator
  • Any provider defined on the injector of the component that is matched by the selector of this query
  • Any provider defined through a string token (e.g. {provide: 'token', useValue: 'val'})
  • TemplateRef, ElementRef, and ViewContainerRef

Usage Notes

import {AfterViewInit, Component, Directive, QueryList, ViewChildren} from '@angular/core';

@Directive({
  selector: 'child-directive',
  standalone: false,
})
class ChildDirective {}

@Component({
  selector: 'someCmp',
  templateUrl: 'someCmp.html',
  standalone: false,
})
class SomeCmp implements AfterViewInit {
  @ViewChildren(ChildDirective) viewChildren!: QueryList<ChildDirective>;

  ngAfterViewInit() {
    // viewChildren is set
  }
}

Another example

import {
  AfterViewInit,
  Component,
  Directive,
  input,
  QueryList,
  signal,
  ViewChildren,
} from '@angular/core';

@Directive({
  selector: 'pane',
  standalone: false,
})
export class Pane {
  id = input.required<string>();
}

@Component({
  selector: 'example-app',
  template: `
    <pane id="1"/>
    <pane id="2"/>
    @if(shouldShow()) {
      <pane id="3"/>
    }

    <button (click)="show()">Show 3</button>

    <div>panes: {{ serializedPanes }}</div>
  `,
  standalone: false,
})
export class ViewChildrenComp implements AfterViewInit {
  @ViewChildren(Pane) panes!: QueryList<Pane>;
  serializedPanes: string = '';

  shouldShow = signal(false);

  show() {
    this.shouldShow.set(true);
  }

  ngAfterViewInit() {
    this.calculateSerializedPanes();
    this.panes.changes.subscribe(() => {
      this.calculateSerializedPanes();
    });
  }

  calculateSerializedPanes() {
    setTimeout(() => {
      this.serializedPanes = this.panes.map((p) => p.id()).join(', ');
    }, 0);
  }
}
Jump to details