ContentChildren

Property decorator that configures a content query.

Use to get the QueryList of elements or directives from the content 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.

Content queries are set before the ngAfterContentInit callback is called.

Does not retrieve elements or directives that are in other components' templates, since a component's template is always a black box to its ancestors.

Metadata Properties:

• selector - The directive type or the name used for querying.
• descendants - If true include all descendants of the element. If false then only query direct children of the element.
• 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.
• read - Used to read a different token from the queried elements.

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 @ContentChildren('cmp'))
• Any provider defined in the child component tree of the current component (e.g. @ContentChildren(SomeService) someService: SomeService)
• Any provider defined through a string token (e.g. @ContentChildren('someToken') someTokenVal: any)
• A TemplateRef (e.g. query <ng-template></ng-template> with @ContentChildren(TemplateRef) template;)

In addition, multiple string selectors can be separated with a comma (e.g. @ContentChildren('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

Here is a simple demonstration of how the ContentChildren decorator can be used.

import {AfterContentInit, ContentChildren, Directive, QueryList} from '@angular/core';@Directive({  selector: 'child-directive',})class ChildDirective {}@Directive({  selector: 'someDir',})class SomeDir implements AfterContentInit {  @ContentChildren(ChildDirective) contentChildren!: QueryList<ChildDirective>;  ngAfterContentInit() {    // contentChildren is set  }}

Tab-pane example

Here is a slightly more realistic example that shows how ContentChildren decorators can be used to implement a tab pane component.

import {Component, ContentChildren, Directive, input, QueryList, signal} from '@angular/core';@Directive({  selector: 'pane',})export class Pane {  id = input.required<string>();}@Component({  selector: 'tab',  template: `    <div class="top-level">Top level panes: {{ serializedPanes }}</div>    <div class="nested">Arbitrary nested panes: {{ serializedNestedPanes }}</div>  `,})export class Tab {  @ContentChildren(Pane) topLevelPanes!: QueryList<Pane>;  @ContentChildren(Pane, {descendants: true}) arbitraryNestedPanes!: QueryList<Pane>;  get serializedPanes(): string {    return this.topLevelPanes ? this.topLevelPanes.map((p) => p.id()).join(', ') : '';  }  get serializedNestedPanes(): string {    return this.arbitraryNestedPanes ? this.arbitraryNestedPanes.map((p) => p.id()).join(', ') : '';  }}@Component({  selector: 'example-app',  imports: [Tab, Pane],  template: `    <tab>      <pane id="1"></pane>      <pane id="2"></pane>      @if(shouldShow()) {        <pane id="3">          <tab>            <pane id="3_1"></pane>            <pane id="3_2"></pane>          </tab>        </pane>      }    </tab>    <button (click)="show()">Show 3</button>  `,})export class ContentChildrenComp {  shouldShow = signal(false);  show() {    this.shouldShow.set(true);  }}