ng-template, ng-container, and ngTemplateOutlet

Intermediate · 16 min

The three building blocks behind every conditional and reusable template fragment in Angular.

Before thisEvent binding and template reference variables

LEARNING PARTNER · 16 min

ng-template, ng-container, and ngTemplateOutlet

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by LEARNING PARTNERReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • `<ng-template>` defines a chunk of markup that Angular doesn't render until something tells it to — it's inert HTML-that-isn't-HTML-yet, not an immediately-rendered element.
  • `<ng-container>` is a grouping wrapper that renders nothing of its own — no extra `<div>`, no attribute — purely there to host a directive or hold content without adding a DOM node.
  • `ngTemplateOutlet` renders an `<ng-template>` on demand, optionally handing it a context object — the same mechanism that powers `@if`, `@for`, and every structural directive under the hood.

Every conditional block needs somewhere to put the “maybe” content

@if and @for feel like built-in language features, but something still has to represent “this markup exists in the template, but shouldn’t always be on the page.” That’s a genuinely different need from “always render this” (what a regular element gives you) — you need a way to describe a fragment of markup that Angular holds onto without inserting into the DOM, and a separate mechanism to decide when (and how many times, and with what data) to actually render it.

Three constructs handle this, and once you’ve seen them directly, the control-flow syntax covered in the next lesson stops looking like magic.

<ng-template>: markup that isn’t rendered yet

<ng-template #loading>
  <p>Loading…</p>
</ng-template>

An <ng-template> never appears in the rendered DOM on its own. Angular parses its contents at compile time and keeps them available — attached here to the template reference variable #loading — but nothing is inserted into the page until something explicitly renders that template. This is the opposite of a normal element, which renders the moment its parent does. An <ng-template> is closer to a function definition than a statement: defining it does nothing by itself; you still have to call it.

<ng-container>: a grouping wrapper with no DOM footprint

<ng-container *ngIf="user">
  <h2>{{ user.name }}</h2>
  <p>{{ user.email }}</p>
</ng-container>

Sometimes you need to apply a directive — a structural directive like *ngIf, or just group several elements for templating purposes — without actually adding a wrapper element to the rendered output. A <div *ngIf="user"> would work, but it adds a <div> that didn’t need to exist, and that extra <div> can break CSS that assumed its children were direct siblings (flex and grid layouts are notorious for this). <ng-container> solves exactly that: it groups elements and can host directives, but renders no DOM node of its own — the two child elements above appear directly in the parent, with nothing wrapping them.

ngTemplateOutlet: rendering a template on demand

<ng-template #greeting let-name="name">
  <p>Hello, {{ name }}!</p>
</ng-template>

<ng-container [ngTemplateOutlet]="greeting" [ngTemplateOutletContext]="{ name: 'Ada' }" />

This is the piece that actually renders an <ng-template>’s content: point ngTemplateOutlet at a template reference, and Angular inserts that template’s content at this spot in the DOM. ngTemplateOutletContext optionally hands the template a data object — let-name="name" inside the template destructures that context, the same let- syntax you may have already seen in *ngFor’s microsyntax.

This is worth sitting with, because it’s not a niche feature — it’s the actual mechanism underneath every structural directive you’ve used. *ngIf and the @if block both work by defining an implicit <ng-template> around their content and conditionally rendering it with something functionally identical to ngTemplateOutlet. Once you’ve written one outlet yourself, the control-flow syntax in the next lesson stops being syntax you memorize and becomes syntax whose mechanics you can already picture.

This lesson’s video walks through all three constructs together, which is the clearest way to see how they compose — the linked “deeper” video goes further into ngTemplateOutlet specifically, including passing more elaborate context objects than the single-value example above.

Where this reappears

Later in this roadmap, the @defer block — Angular’s built-in lazy-rendering syntax — uses this same “inert content until triggered” idea, just with a loading state and a network boundary added on top. Seeing <ng-template> and ngTemplateOutlet here first is what makes @defer’s placeholder/loading/error sub-blocks make immediate sense later.

Check yourself

  1. 01If you wrap three elements in `<ng-container>` instead of a `<div>`, what shows up in the rendered DOM at that spot?

    Just the three elements, with nothing wrapping them — `<ng-container>` itself never renders a DOM node. It's a template-only grouping construct, which is exactly why it's the right tool when you need to apply a directive to a group of elements without introducing an extra wrapper `<div>` that could break your CSS layout.

  2. 02What has to happen for the content inside an `<ng-template>` to actually appear on the page?

    Something has to explicitly render it — most commonly `ngTemplateOutlet`, or a structural directive like `@if`/`*ngIf` under the hood. On its own, an `<ng-template>`'s content is inert: Angular parses it but doesn't insert it into the DOM until told to.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark