{ "id": "api/common/NgIf", "title": "NgIf", "contents": "\n\n
\n
\n
\n \n API > @angular/common\n
\n \n
\n \n
\n

NgIflink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

A structural directive that conditionally includes a template based on the value of\nan expression coerced to Boolean.\nWhen the expression evaluates to true, Angular renders the template\nprovided in a then clause, and when false or null,\nAngular renders the template provided in an optional else clause. The default\ntemplate for the else clause is blank.

\n\n

See more...

\n
\n \n \n \n \n\n

NgModulelink

\n\n\n\n \n
\n

Selectorslink

\n \n \n \n
\n\n\n\n \n\n
\n

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n @Input()
ngIf: T
\n
Write-Only\n \n

The Boolean expression to evaluate as the condition for showing a template.

\n\n \n
\n \n @Input()
ngIfThen: TemplateRef<NgIfContext<T>>
\n
Write-Only\n \n

A template to show if the condition expression evaluates to true.

\n\n \n
\n \n @Input()
ngIfElse: TemplateRef<NgIfContext<T>>
\n
Write-Only\n \n

A template to show if the condition expression evaluates to false.

\n\n \n
\n
\n\n\n\n \n\n\n \n
\n

Descriptionlink

\n

A shorthand form of the directive,\n*ngIf=\"condition\", is generally used, provided\nas an attribute of the anchor element for the inserted template.\nAngular expands this into a more explicit version, in which the anchor element\nis contained in an <ng-template> element.

\n

Simple form with shorthand syntax:

\n\n<div *ngIf=\"condition\">Content to render when condition is true.</div>\n\n

Simple form with expanded syntax:

\n\n<ng-template [ngIf]=\"condition\"><div>Content to render when condition is\ntrue.</div></ng-template>\n\n

Form with an \"else\" block:

\n\n<div *ngIf=\"condition; else elseBlock\">Content to render when condition is true.</div>\n<ng-template #elseBlock>Content to render when condition is false.</ng-template>\n\n

Shorthand form with \"then\" and \"else\" blocks:

\n\n<div *ngIf=\"condition; then thenBlock else elseBlock\"></div>\n<ng-template #thenBlock>Content to render when condition is true.</ng-template>\n<ng-template #elseBlock>Content to render when condition is false.</ng-template>\n\n

Form with storing the value locally:

\n\n<div *ngIf=\"condition as value; else elseBlock\">{{value}}</div>\n<ng-template #elseBlock>Content to render when value is null.</ng-template>\n\n\n

The *ngIf directive is most commonly used to conditionally show an inline template,\nas seen in the following example.\nThe default else template is blank.

\n\n@Component({\n selector: 'ng-if-simple',\n template: `\n <button (click)=\"show = !show\">{{show ? 'hide' : 'show'}}</button>\n show = {{show}}\n <br>\n <div *ngIf=\"show\">Text to show</div>\n`\n})\nexport class NgIfSimple {\n show = true;\n}\n\n\n

Showing an alternative template using elselink

\n

To display a template when expression evaluates to false, use an else template\nbinding as shown in the following example.\nThe else binding points to an <ng-template> element labeled #elseBlock.\nThe template can be defined anywhere in the component view, but is typically placed right after\nngIf for readability.

\n\n@Component({\n selector: 'ng-if-else',\n template: `\n <button (click)=\"show = !show\">{{show ? 'hide' : 'show'}}</button>\n show = {{show}}\n <br>\n <div *ngIf=\"show; else elseBlock\">Text to show</div>\n <ng-template #elseBlock>Alternate text while primary text is hidden</ng-template>\n`\n})\nexport class NgIfElse {\n show = true;\n}\n\n\n

Using an external then templatelink

\n

In the previous example, the then-clause template is specified inline, as the content of the\ntag that contains the ngIf directive. You can also specify a template that is defined\nexternally, by referencing a labeled <ng-template> element. When you do this, you can\nchange which template to use at runtime, as shown in the following example.

\n\n@Component({\n selector: 'ng-if-then-else',\n template: `\n <button (click)=\"show = !show\">{{show ? 'hide' : 'show'}}</button>\n <button (click)=\"switchPrimary()\">Switch Primary</button>\n show = {{show}}\n <br>\n <div *ngIf=\"show; then thenBlock; else elseBlock\">this is ignored</div>\n <ng-template #primaryBlock>Primary text to show</ng-template>\n <ng-template #secondaryBlock>Secondary text to show</ng-template>\n <ng-template #elseBlock>Alternate text while primary text is hidden</ng-template>\n`\n})\nexport class NgIfThenElse implements OnInit {\n thenBlock: TemplateRef<any>|null = null;\n show = true;\n\n @ViewChild('primaryBlock', {static: true}) primaryBlock: TemplateRef<any>|null = null;\n @ViewChild('secondaryBlock', {static: true}) secondaryBlock: TemplateRef<any>|null = null;\n\n switchPrimary() {\n this.thenBlock = this.thenBlock === this.primaryBlock ? this.secondaryBlock : this.primaryBlock;\n }\n\n ngOnInit() {\n this.thenBlock = this.primaryBlock;\n }\n}\n\n\n

Storing a conditional result in a variablelink

\n

You might want to show a set of properties from the same object. If you are waiting\nfor asynchronous data, the object can be undefined.\nIn this case, you can use ngIf and store the result of the condition in a local\nvariable as shown in the following example.

\n\n@Component({\n selector: 'ng-if-as',\n template: `\n <button (click)=\"nextUser()\">Next User</button>\n <br>\n <div *ngIf=\"userObservable | async as user; else loading\">\n Hello {{user.last}}, {{user.first}}!\n </div>\n <ng-template #loading let-user>Waiting... (user is {{user|json}})</ng-template>\n`\n})\nexport class NgIfAs {\n userObservable = new Subject<{first: string, last: string}>();\n first = ['John', 'Mike', 'Mary', 'Bob'];\n firstIndex = 0;\n last = ['Smith', 'Novotny', 'Angular'];\n lastIndex = 0;\n\n nextUser() {\n let first = this.first[this.firstIndex++];\n if (this.firstIndex >= this.first.length) this.firstIndex = 0;\n let last = this.last[this.lastIndex++];\n if (this.lastIndex >= this.last.length) this.lastIndex = 0;\n this.userObservable.next({first, last});\n }\n}\n\n\n

This code uses only one AsyncPipe, so only one subscription is created.\nThe conditional statement stores the result of userStream|async in the local variable user.\nYou can then bind the local user repeatedly.

\n

The conditional displays the data only if userStream returns a value,\nso you don't need to use the\nsafe-navigation-operator (?.)\nto guard against null values when accessing properties.\nYou can display an alternative template while waiting for the data.

\n

Shorthand syntaxlink

\n

The shorthand syntax *ngIf expands into two separate template specifications\nfor the \"then\" and \"else\" clauses. For example, consider the following shorthand statement,\nthat is meant to show a loading page while waiting for data to be loaded.

\n\n<div class=\"hero-list\" *ngIf=\"heroes else loading\">\n ...\n</div>\n\n<ng-template #loading>\n <div>Loading...</div>\n</ng-template>\n\n

You can see that the \"else\" clause references the <ng-template>\nwith the #loading label, and the template for the \"then\" clause\nis provided as the content of the anchor element.

\n

However, when Angular expands the shorthand syntax, it creates\nanother <ng-template> tag, with ngIf and ngIfElse directives.\nThe anchor element containing the template for the \"then\" clause becomes\nthe content of this unlabeled <ng-template> tag.

\n\n<ng-template [ngIf]=\"heroes\" [ngIfElse]=\"loading\">\n <div class=\"hero-list\">\n ...\n </div>\n</ng-template>\n\n<ng-template #loading>\n <div>Loading...</div>\n</ng-template>\n\n

The presence of the implicit template object has implications for the nesting of\nstructural directives. For more on this subject, see\nStructural Directives.

\n\n
\n \n\n \n
\n

Static propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n static ngTemplateGuard_ngIf: 'binding'\n \n \n

Assert the correct type of the expression bound to the ngIf input within the template.

\n\n

The presence of this static field is a signal to the Ivy template type check compiler that\nwhen the NgIf structural directive renders its template, the type of the expression bound\nto ngIf should be narrowed in some way. For NgIf, the binding expression itself is used to\nnarrow its type, which allows the strictNullChecks feature of TypeScript to work with NgIf.

\n\n
\n
\n \n\n
\n

Static methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n
\n
\n

\n ngTemplateContextGuard()\n \n link

\n \n
\n
\n

Asserts the correct type of the context for the template that NgIf will render.

\n\n
\n
\n \n\n static ngTemplateContextGuard<T>(dir: NgIf<T>, ctx: any): ctx is NgIfContext<Exclude<T, false | 0 | '' | null | undefined>>\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgIf\n \n \n
\n \n ctx\n any\n \n \n
\n\n \n
Returns
\n

ctx is NgIfContext<Exclude<T, false | 0 | '' | null | undefined>>

\n\n \n\n\n \n\n \n
\n
\n

The presence of this method is a signal to the Ivy template type-check compiler that the\nNgIf structural directive renders its template with a specific context type.

\n\n
\n\n \n
\n\n \n\n \n \n \n\n
\n
\n\n\n" }