block includes include ../_util-fns // The docs standard h4 style uppercases, making code terms unreadable. Override it. style. h4 {font-size: 17px !important; text-transform: none !important;} .syntax { font-family: Consolas, 'Lucida Sans', Courier, sans-serif; color: black; font-size: 85%; } :marked This guide has been withdrawn. The essential information about this feature is in the [Structural Directives](structural-directives.html#ngcontainer) guide. The original draft has been retained for possible future use. // :marked The `` tags are part of Angular template syntax. They help you group HTML template content under a phantom _root_ element that you can manipulate with [structural directives](#structural-directives.html). This guide explains how `` solves certain layout problems. ### Table of contents - [Introduction](#introduction) - [The problem](#problem) - [Troublesome CSS](#CSS) - [Restrictive layout](#restrictive-layout) - [<ng-container> is excluded from DOM](#excluded) - [<ng-container> is not <ng-content>](#ng-content) - [Summary](#summary) Try the . a#introduction .l-main-section :marked ## Introduction Structural directives are responsible for HTML layout. They shape or reshape the DOM's _structure_, typically by adding and removing other elements and their children. Two of the common, built-in structural directives are [NgIf](template-syntax.html#ngIf) and [NgFor](template-syntax.html#ngFor). You apply these directives to elements that Angular should add and remove. Usually there's _one_ obvious element to receive the directive. Sometimes you need to add or remove a _group of sibling elements_. You want to apply the directive to the group, not just one of them. As this guide explains, you can wrap the elements in an `` and apply the directive to the ``. The `` is Angular template syntax for grouping elements, like the curly braces that group statements in a JavaScript `if` block: code-example(language="javascript"). if (someCondition) { statement1; statement2; statement3; } :marked Without those braces JavaScript could only execute the first statement1 when you intend to conditionally execute all (or none) of the statements as a single block. The `` satisfies a similar need in Angular templates. The `` _is not_ a directive. It's not a class or interface or anything you could find in the [API guide](../api "API guide"). It's just grouping syntax recognized by the Angular parser. *Why bother?* Why not wrap the group in standard HTML container element such as `` or `
`? The rest of this guide answers these questions after stepping back and reframing the problem in a bit more detail. a#problem .l-main-section :marked ## The problem There's often a _root_ element that can and should host the structural directive. In the following example, the table row (``) should appear only when showing structural directives (when `strucDirs` is `true`). +makeExample('ngcontainer/ts/src/app/app.component.html', 'ngif-tr')(format=".") :marked When there isn't a host element, you can usually wrap the content in a native HTML container element, such as a `
`, and attach the directive to that wrapper. +makeExample('ngcontainer/ts/src/app/app.component.html', 'ngif')(format=".") :marked Introducing another container element is usually harmless. _Usually_ ... but not _always_. a#css :marked ### Troublesome CSS CSS styles can be persnickety about HTML structure, making it difficult to introduce intermediate container elements. Suppose you want to display a paragraph with a single sentence that describes the traits of a hero. figure.image-display img(src='/resources/images/devguide/ngcontainer/hero-traits-good.png' alt="hero traits") :marked For reasons unknown, you can't do the obvious thing and construct the text in a component property. You must build the sentence in the template instead. You try a combination of `` wrappers, `*ngIf`, and `*ngFor` and write this. +makeExample('ngcontainer/ts/src/app/app.component.html', 'ngif-span-2')(format=".") :marked Unfortunately, there's a style that kicks in when a `

`aragraph contains a ``. +makeExample('ngcontainer/ts/src/app/app.component.css', 'p-span')(format=".") :marked So the sentence renders the spanned text in tiny, red type like this. figure.image-display img(src='/resources/images/devguide/ngcontainer/hero-traits-bad.png' alt="hero traits (oops)") :marked You could try to fix the CSS ... if you have permission to do so. The far easier approach is to use `` instead of `` like this. +makeExample('ngcontainer/ts/src/app/app.component.html', 'ngif-ngcontainer-2')(format=".") a#excluded :marked ### <ng-container> is excluded from the DOM That works. There are no `` tags to trigger the unwanted style. Does Angular add an `` to the DOM? If it did, you'd trip over a similar problem someday, because the introduction of _any_ HTML for layout purposes is a potential hazard. Fortunately, Angular _replaces_ `` _with comments_, which have no effect on styles or layout. Inspect the rendered HTML in the browser tools. You'll see many comments like this: code-example(language="html" escape="html"). <!--template bindings={ "ng-reflect-ng-if": "true" }--> <!--template bindings={} --> :marked You won't find ``. That's especially important when applying structural directives to the children of certain troublesome HTML elements. a#restrictive-layout :marked ### <ng-container> and restrictive layout Some HTML elements are picky about their children. For example, all children of a `