What are practical scenarios of *ngTemplateOutlet directive?

Question

I was reading about *ngTemplateOutlet directive. The use of this directive is to instantiate a template dynamically by a template reference and context object as parameters.

What I want to know is that we have so many things in Angular to achieve the same results as *ngTemplateOutlet such as:

1. We can have multiple *ngIf which could render different templates based on the component variable value within the same component. In a similar fashion we have [ngSwitch] which would render different templates for us based on different values.

2. We could use references with *ngIf by referring to the template reference variable of the respective variable.

For the former case:

<div *ngIf="condition1"> Content 1 </div>
<div *ngIf="condition2"> Content 2 </div>
<div *ngIf="condition3"> Content 3 </div>

And for latter:

<ng-container *ngIf="condition then myTemplate else otherTemplate"></ng-container>
<ng-template #myTemplate> Some content... </ng-template>
<ng-template #otherTemplate> Some content... </ng-template>

If we have such methods in our arsenal what more value does *ngTemplateOutlet add?

What are the practical use cases (if there are any) where we cannot use the above methods and should use *ngTemplateOutlet directive or is it just another method to choose from to achieve the same result?

Answer 1

One thing that makes *ngTemplateOutlet more powerful than *ng-content is when you use it with [ngTemplateOutletContext] input. This enables you to create a totally unique template that can use state from within the component.

I have used this to create a select component that is uniquely styled per client, via different templates, but shares exactly the same code. Here is a StackBlitz link and also my article about it on indepth.dev.

One example of a benefit of *ngTemplateOutlets over using *ngIfs is that your component does not need to depend on external packages, i.e an Icon lib, if this is only going to be used by a single client.

Answer 2

The true power of ngTemplateOutlet can be seen when you need to deal with nested items where you don't know how many levels deep you could go. Doing an ngFor or ngSwitch is cumbersome when dealing with nested arrays, and limited as you always need to know beforehand how many levels deep you want to go:

For example:

If this is my array:

  todo = [
    'Get to work',
    [
      'Get up',
      'Brush teeth',
      'Take a shower',
      'Check e-mail',
      'Walk dog'
    ],
    [
      'Prepare for work',
      'Drive to office',
      'Park car',
      'Work',
      [
        'See Clients',
        'Fill Out Forms',
        'Take Tea Breaks',
        [
          'Switch on Kettle',
          'Get Clean Cup',
          'Add Tea',
          'Pour Water',
          'Drink'
        ]
      ]
    ],
    'Pick up groceries',
    'Go home',
    'Fall asleep'
  ];

Then you could use the following approach:

<div *ngFor="let item of todo" style="margin-left: 25px">

  <div *ngIf="!isArray(item); else arrayView">{{item}}</div>
  <ng-template #arrayView>

    <div *ngFor="let item2 of item" style="margin-left: 25px">

      <p>And So On...</p>

    </div>

  </ng-template>

</div>

But what if you don't know how many levels deep your array goes? You could use ngTemplateOutlet in conjunction with an ng-template instead, to take care of the problem:

<ng-template #tmplItems let-todo="todo">

  <div *ngFor="let item of todo" style="margin-left: 25px">

    <div *ngIf="!isArray(item); else arrayView">{{item}}</div>
    <ng-template #arrayView>

      <ng-container *ngTemplateOutlet="tmplItems,context:{todo:item}">

      </ng-container>

    </ng-template>

  </div>

</ng-template>

<div *ngFor="let item of todo">

  <div *ngIf="!isArray(item); else arrayView">{{item}}</div>
  <ng-template #arrayView>

    <ng-container *ngTemplateOutlet="tmplItems,context:{todo:item}">

    </ng-container>

  </ng-template>

</div>

Now it doesn't matter how many levels deep your array goes, calling your ng-template recursively takes care of the problem (unless there is a limitation that I'm not aware of yet).

Output:

Get to work
    Get up
    Brush teeth
    Take a shower
    Check e-mail
    Walk dog
    Prepare for work
    Drive to office
    Park car
    Work
        See Clients
        Fill Out Forms
        Take Tea Breaks
            Switch on Kettle
            Get Clean Cup
            Add Tea
            Pour Water
            Drink
Pick up groceries
Go home
Fall asleep

Answer 3

Angular template outlets can be used to insert a common template in various sections of a view that are not generated by a loop or subject to a condition. For example, you can define a template for the logo of a company and insert it in several places in the page:

<div>
  <ng-container *ngTemplateOutlet="companyLogoTemplate"></ng-container>
  <h1>Company History</h1>
  <div>{{companyHistory}}</div>
</div>
<form (ngSubmit)="onSubmit()">
  <ng-container *ngTemplateOutlet="companyLogoTemplate"></ng-container>
  <h1>User info</h1>
  <label>Name:</label><input type="text" [(ngModel)]="userName" />
  <label>Account ID:</label><input type="text" [(ngModel)]="accountId" />
  <button>Submit</button>
</form>
<div class="footer">
  <ng-container *ngTemplateOutlet="companyLogoTemplate"></ng-container>
</div>

<ng-template #companyLogoTemplate>
  <div class="companyLogo">
    <img [src]="logoSourceUrl">
    <label>The ACME company, {{employeeCount}} people working for you!</label>
  </div>
</ng-template>

---

Templates and template outlets can also help to make a component configurable. The following example is taken from this article by Angular University.

A tab container component defines a default tab header template, but allows to override it with a custom template defined as an input property. The appropriate template (default or custom) is then inserted in the view with a template outlet:

@Component({
  selector: 'tab-container',
  template: `
    <ng-template #defaultTabButtons>
      <div class="default-tab-buttons">
        ...
      </div>
    </ng-template>
    <ng-container *ngTemplateOutlet="headerTemplate || defaultTabButtons"></ng-container>
    ... rest of tab container component ...
  `
})
export class TabContainerComponent {
    @Input() headerTemplate: TemplateRef<any>; // Custom template provided by parent
}

In the parent component, you define the custom tab header template and pass it to the tab container component:

@Component({
  selector: 'app-root',
  template: `      
    <ng-template #customTabButtons>
      <div class="custom-class">
        <button class="tab-button" (click)="login()">
          {{loginText}}
        </button>
        <button class="tab-button" (click)="signUp()">
          {{signUpText}}
        </button>
      </div>
    </ng-template>
    <tab-container [headerTemplate]="customTabButtons"></tab-container>      
  `
})
export class AppComponent implements OnInit {
  ...
}

You can see another advanced use case in this blog post by alligator.io.

Answer 4

You have very valid question. If something can be achieved by simple if or switch case, why should we use *ngTemplateOutlet?

Independent Component

You are getting these thought because you are thinking about one independent Component level. In other words everything condition, templates are in the same component. We can easily select the template on the basis of certain condition.

Library Component

Dynamic Template

When I say Library Component, it means generic reusable component ex Autocompleter or Typeahead etc. These components provides the functional part however they allow the developer to choose their own template as per their needs.

Here is the catch now, these templates doesn't reside the Autocompleter, it comes from its @ContentChild.

ex:

<ng-autocompleter>
   <ng-template #item let-item>{{item.name}}</ng-template>
<ng-autocompleter>

In above example the <ng-template> is being defined the developer later point time and its not the direct part of <ng-autocompleter>.

Template Context

Template context is very important whenever highly configured component is developed. Getting the dynamic template (html) is not good enough to serve the purpose. We need to bind the value to the ng-template. Since ng-template is not in the part of ng-autocompleter we need to pass the context which contains all necessary data to bind.

ex : In above case if you see we declared the item variable by let-item but where is item is coming from. That will be decided by the context given to *ngTemplateOutlet.

One line conclusion If we want to inject the templates which is will be declared in future by someone, I cannot handle this case by *ngIf or *ngSwitch. We need to use *ngTemplateOutlet.