Built-in directives link

Directives are classes that add additional behavior to elements in your Angular applications. Use Angular's built-in directives to manage forms, lists, styles, and what users see.

The different types of Angular directives are as follows:

This guide covers built-in attribute directives and structural directives.

Built-in attribute directives link

Attribute directives listen to and modify the behavior of other HTML elements, attributes, properties, and components.

Many NgModules such as the RouterModule and the FormsModule define their own attribute directives. The most common attribute directives are as follows:

Adding and removing classes with NgClass link

Add or remove multiple CSS classes simultaneously with ngClass .

Using NgClass with an expression link

On the element you'd like to style, add [ngClass] and set it equal to an expression. In this case, isSpecial is a boolean set to true in app.component.ts . Because isSpecial is true, ngClass applies the class of special to the <div> .

      
        content_copy
      
      <!-- toggle the "special" class on/off with a property -->
<div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>
    

Using NgClass with a method link

1. To use NgClass with a method, add the method to the component class. In the following example, setCurrentClasses() sets the property currentClasses with an object that adds or removes three classes based on the true or false state of three other component properties.

   Each key of the object is a CSS class name. If a key is true , ngClass adds the class. If a key is false , ngClass removes the class.

   src/app/app.component.ts

         
           content_copy
         
         currentClasses: Record<string, boolean> = {};
   /* . . . */
   setCurrentClasses() {
     // CSS classes: added/removed per current state of component properties
     this.currentClasses =  {
       saveable: this.canSave,
       modified: !this.isUnchanged,
       special:  this.isSpecial
     };
   }
       

2. In the template, add the ngClass property binding to currentClasses to set the element's classes:

   src/app/app.component.html

         
           content_copy
         
         <div [ngClass]="currentClasses">This div is initially saveable, unchanged, and special.</div>
       

For this use case, Angular applies the classes on initialization and in case of changes. The full example calls setCurrentClasses() initially with ngOnInit() and when the dependent properties change through a button click. These steps are not necessary to implement ngClass . For more information, see the live example / download example app.component.ts and app.component.html .

Setting inline styles with NgStyle link

Use NgStyle to set multiple inline styles simultaneously, based on the state of the component.

1. To use NgStyle , add a method to the component class.

   In the following example, setCurrentStyles() sets the property currentStyles with an object that defines three styles, based on the state of three other component properties.

   src/app/app.component.ts

         
           content_copy
         
         currentStyles: Record<string, string> = {};
   /* . . . */
   setCurrentStyles() {
     // CSS styles: set per current state of component properties
     this.currentStyles = {
       'font-style':  this.canSave      ? 'italic' : 'normal',
       'font-weight': !this.isUnchanged ? 'bold'   : 'normal',
       'font-size':   this.isSpecial    ? '24px'   : '12px'
     };
   }
       

2. To set the element's styles, add an ngStyle property binding to currentStyles .

   src/app/app.component.html

         
           content_copy
         
         <div [ngStyle]="currentStyles">
     This div is initially italic, normal weight, and extra large (24px).
   </div>
       

For this use case, Angular applies the styles upon initialization and in case of changes. To do this, the full example calls setCurrentStyles() initially with ngOnInit() and when the dependent properties change through a button click. However, these steps are not necessary to implement ngStyle on its own. See the live example / download example app.component.ts and app.component.html for this optional implementation.

Displaying and updating properties with ngModel link

Use the NgModel directive to display a data property and update that property when the user makes changes.

1. Import FormsModule and add it to the NgModule's imports list.

   src/app/app.module.ts (FormsModule import)

         
           content_copy
         
         import { FormsModule } from '@angular/forms'; // <--- JavaScript import from Angular
   /* . . . */
   @NgModule({
     /* . . . */
   
     imports: [
       BrowserModule,
       FormsModule // <--- import into the NgModule
     ],
     /* . . . */
   })
   export class AppModule { }
       

2. Add an [(ngModel)] binding on an HTML <form> element and set it equal to the property, here name .

   src/app/app.component.html (NgModel example)

         
           content_copy
         
         <label for="example-ngModel">[(ngModel)]:</label>
   <input [(ngModel)]="currentItem.name" id="example-ngModel">
       

   This [(ngModel)] syntax can only set a data-bound property.

To customize your configuration, write the expanded form, which separates the property and event binding. Use property binding to set the property and event binding to respond to changes. The following example changes the <input> value to uppercase:

      
        content_copy
      
      <input [ngModel]="currentItem.name" (ngModelChange)="setUppercaseName($event)" id="example-uppercase">
    

Here are all variations in action, including the uppercase version:

NgModel and value accessors link

The NgModel directive works for an element supported by a ControlValueAccessor. Angular provides value accessors for all of the basic HTML form elements. For more information, see Forms.

To apply [(ngModel)] to a non-form built-in element or a third-party custom component, you have to write a value accessor. For more information, see the API documentation on DefaultValueAccessor.

Built-in structural directives link

Structural directives are responsible for HTML layout. They shape or reshape the DOM's structure, typically by adding, removing, and manipulating the host elements to which they are attached.

This section introduces the most common built-in structural directives:

For more information, see Structural Directives.

Adding or removing an element with NgIf link

Add or remove an element by applying an NgIf directive to a host element.

When NgIf is false , Angular removes an element and its descendants from the DOM. Angular then disposes of their components, which frees up memory and resources.

To add or remove an element, bind *ngIf to a condition expression such as isActive in the following example.

      
        content_copy
      
      <app-item-detail *ngIf="isActive" [item]="item"></app-item-detail>
    

When the isActive expression returns a truthy value, NgIf adds the ItemDetailComponent to the DOM. When the expression is falsy, NgIf removes the ItemDetailComponent from the DOM and disposes of the component and all of its subcomponents.

For more information on NgIf and NgIfElse , see the NgIf API documentation.

Guarding against null link

By default, NgIf prevents display of an element bound to a null value.

To use NgIf to guard a <div> , add *ngIf="yourProperty" to the <div> . In the following example, the currentCustomer name appears because there is a currentCustomer .

      
        content_copy
      
      <div *ngIf="currentCustomer">Hello, {{currentCustomer.name}}</div>
    

However, if the property is null , Angular does not display the <div> . In this example, Angular does not display the nullCustomer because it is null .

      
        content_copy
      
      <div *ngIf="nullCustomer">Hello, <span>{{nullCustomer}}</span></div>
    

Listing items with NgFor link

Use the NgFor directive to present a list of items.

1. Define a block of HTML that determines how Angular renders a single item.
2. To list your items, assign the shorthand let item of items to *ngFor .

      
        content_copy
      
      <div *ngFor="let item of items">{{item.name}}</div>
    

The string "let item of items" instructs Angular to do the following:

• Store each item in the items array in the local item looping variable
• Make each item available to the templated HTML for each iteration
• Translate "let item of items" into an <ng-template> around the host element
• Repeat the <ng-template> for each item in the list

For more information see the Structural directive shorthand section of Structural directives.

Repeating a component view link

To repeat a component element, apply *ngFor to the selector. In the following example, the selector is <app-item-detail> .

      
        content_copy
      
      <app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>
    

Reference a template input variable, such as item , in the following locations:

• Within the ngFor host element
• Within the host element descendants to access the item's properties

The following example references item first in an interpolation and then passes in a binding to the item property of the <app-item-detail> component.

      
        content_copy
      
      <div *ngFor="let item of items">{{item.name}}</div>
<!-- . . . -->
<app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>
    

For more information about template input variables, see Structural directive shorthand.

Getting the index of *ngFor link

Get the index of *ngFor in a template input variable and use it in the template.

In the *ngFor , add a semicolon and let i=index to the shorthand. The following example gets the index in a variable named i and displays it with the item name.

      
        content_copy
      
      <div *ngFor="let item of items; let i=index">{{i + 1}} - {{item.name}}</div>
    

The index property of the NgFor directive context returns the zero-based index of the item in each iteration.

Angular translates this instruction into an <ng-template> around the host element, then uses this template repeatedly to create a new set of elements and bindings for each item in the list. For more information about shorthand, see the Structural Directives guide.

Repeating elements when a condition is true link

To repeat a block of HTML when a particular condition is true, put the *ngIf on a container element that wraps an *ngFor element.

For more information see one structural directive per element.

Tracking items with *ngFor trackBy link

Reduce the number of calls your application makes to the server by tracking changes to an item list. With the *ngFor trackBy property, Angular can change and re-render only those items that have changed, rather than reloading the entire list of items.

1. Add a method to the component that returns the value NgFor should track. In this example, the value to track is the item's id . If the browser has already rendered id , Angular keeps track of it and doesn't re-query the server for the same id .

   src/app/app.component.ts

         
           content_copy
         
         trackByItems(index: number, item: Item): number { return item.id; }
       

2. In the shorthand expression, set trackBy to the trackByItems() method.

   src/app/app.component.html

         
           content_copy
         
         <div *ngFor="let item of items; trackBy: trackByItems">
     ({{item.id}}) {{item.name}}
   </div>
       

Change ids creates new items with new item.id s. In the following illustration of the trackBy effect, Reset items creates new items with the same item.id s.

• With no trackBy , both buttons trigger complete DOM element replacement.
• With trackBy , only changing the id triggers element replacement.

Hosting a directive without a DOM element link

The Angular <ng-container> is a grouping element that doesn't interfere with styles or layout because Angular doesn't put it in the DOM.

Use <ng-container> when there's no single element to host the directive.

Here's a conditional paragraph using <ng-container> .

      
        content_copy
      
      <p>
  I turned the corner
  <ng-container *ngIf="hero">
    and saw {{hero.name}}. I waved
  </ng-container>
  and continued on my way.
</p>
    

1. Import the ngModel directive from FormsModule .

2. Add FormsModule to the imports section of the relevant Angular module.

3. To conditionally exclude an <option> , wrap the <option> in an <ng-container> .

   src/app/app.component.html (select-ngcontainer)

         
           content_copy
         
         <div>
     Pick your favorite hero
     (<label><input type="checkbox" checked (change)="showSad = !showSad">show sad</label>)
   </div>
   <select [(ngModel)]="hero">
     <ng-container *ngFor="let h of heroes">
       <ng-container *ngIf="showSad || h.emotion !== 'sad'">
         <option [ngValue]="h">{{h.name}} ({{h.emotion}})</option>
       </ng-container>
     </ng-container>
   </select>
       

   

Switching cases with NgSwitch link

Like the JavaScript switch statement, NgSwitch displays one element from among several possible elements, based on a switch condition. Angular puts only the selected element into the DOM.

NgSwitch is a set of three directives:

1. On an element, such as a <div> , add [ngSwitch] bound to an expression that returns the switch value, such as feature . Though the feature value in this example is a string, the switch value can be of any type.

2. Bind to *ngSwitchCase and *ngSwitchDefault on the elements for the cases.

   src/app/app.component.html

         
           content_copy
         
         <div [ngSwitch]="currentItem.feature">
     <app-stout-item    *ngSwitchCase="'stout'"    [item]="currentItem"></app-stout-item>
     <app-device-item   *ngSwitchCase="'slim'"     [item]="currentItem"></app-device-item>
     <app-lost-item     *ngSwitchCase="'vintage'"  [item]="currentItem"></app-lost-item>
     <app-best-item     *ngSwitchCase="'bright'"   [item]="currentItem"></app-best-item>
   <!-- . . . -->
     <app-unknown-item  *ngSwitchDefault           [item]="currentItem"></app-unknown-item>
   </div>
       

3. In the parent component, define currentItem , to use it in the [ngSwitch] expression.

   src/app/app.component.ts

         
           content_copy
         
         currentItem!: Item;
       

4. In each child component, add an item input property which is bound to the currentItem of the parent component. The following two snippets show the parent component and one of the child components. The other child components are identical to StoutItemComponent .

   In each child component, here StoutItemComponent

         
           content_copy
         
         export class StoutItemComponent {
     @Input() item!: Item;
   }
       

   

Switch directives also work with built-in HTML elements and web components. For example, you could replace the <app-best-item> switch case with a <div> as follows.

      
        content_copy
      
      <div *ngSwitchCase="'bright'"> Are you as bright as {{currentItem.name}}?</div>
    

What's next link

For information on how to build your own custom directives, see Attribute Directives and Structural Directives.

Skipping component subtrees link

JavaScript, by default, uses mutable data structures that you can reference from multiple different components. Angular runs change detection over your entire component tree to make sure that the most up-to-date state of your data structures is reflected in the DOM.

Change detection is sufficiently fast for most applications. However, when an application has an especially large component tree, running change detection across the whole application can cause performance issues. You can address this by configuring change detection to only run on a subset of the component tree.

If you are confident that a part of the application is not affected by a state change, you can use OnPush to skip change detection in an entire component subtree.

Using OnPush link

OnPush change detection instructs Angular to run change detection for a component subtree only when:

• The root component of the subtree receives new inputs as the result of a template binding. Angular compares the current and past value of the input with ==
• Angular handles an event (for example using event binding, output binding, or @HostListener ) in the subtree's root component or any of its children whether they are using OnPush change detection or not.

You can set the change detection strategy of a component to OnPush in the @Component decorator:

      
        content_copy
      
      import { ChangeDetectionStrategy, Component } from '@angular/core';
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyComponent {}
    

Common change detection scenarios link

This section examines several common change detection scenarios to illustrate Angular's behavior.

An event is handled by a component with default change detection link

If Angular handles an event within a component without OnPush strategy, the framework executes change detection on the entire component tree. Angular will skip descendant component subtrees with roots using OnPush , which have not received new inputs.

As an example, if we set the change detection strategy of MainComponent to OnPush and the user interacts with a component outside the subtree with root MainComponent , Angular will check all the green components from the diagram below ( AppComponent , HeaderComponent , SearchComponent , ButtonComponent ) unless MainComponent receives new inputs:

An event is handled by a component with OnPush link

If Angular handles an event within a component with OnPush strategy, the framework will execute change detection within the entire component tree. Angular will ignore component subtrees with roots using OnPush, which have not received new inputs and are outside the component which handled the event.

As an example, if Angular handles an event within MainComponent , the framework will run change detection in the entire component tree. Angular will ignore the subtree with root LoginComponent because it has OnPush and the event happened outside of its scope.

An event is handled by a descendant of a component with OnPush link

If Angular handles an event in a component with OnPush, the framework will execute change detection in the entire component tree, including the component’s ancestors.

As an example, in the diagram below, Angular handles an event in LoginComponent which uses OnPush. Angular will invoke change detection in the entire component subtree including MainComponent ( LoginComponent ’s parent), even though MainComponent has OnPush as well. Angular checks MainComponent as well because LoginComponent is part of its view.

New inputs to component with OnPush link

Angular will run change detection within a child component with OnPush setting an input property as result of a template binding.

For example, in the diagram below, AppComponent passes a new input to MainComponent , which has OnPush . Angular will run change detection in MainComponent but will not run change detection in LoginComponent , which also has OnPush , unless it receives new inputs as well.

Edge cases link

• Modifying input properties in TypeScript code . When you use an API like @ViewChild or @ContentChild to get a reference to a component in TypeScript and manually modify an @Input property, Angular will not automatically run change detection for OnPush components. If you need Angular to run change detection, you can inject ChangeDetectorRef in your component and call changeDetectorRef.markForCheck() to tell Angular to schedule a change detection.
• Modifying object references . In case an input receives a mutable object as value and you modify the object but preserve the reference, Angular will not invoke change detection. That’s the expected behavior because the previous and the current value of the input point to the same reference.

Slow computations link

On every change detection cycle, Angular synchronously:

• Evaluates all template expressions in all components, unless specified otherwise, based on that each component's detection strategy
• Executes the ngDoCheck , ngAfterContentChecked , ngAfterViewChecked , and ngOnChanges lifecycle hooks. A single slow computation within a template or a lifecycle hook can slow down the entire change detection process because Angular runs the computations sequentially.

Identifying slow computations link

You can identify heavy computations with Angular DevTools’ profiler. In the performance timeline, click a bar to preview a particular change detection cycle. This displays a bar chart, which shows how long the framework spent in change detection for each component. When you click a component, you can preview how long Angular spent evaluating its template and lifecycle hooks.

For example, in the preceding screenshot, the second recorded change detection cycle is selected. Angular spent over 573 ms on this cycle, with the most time spent in the EmployeeListComponent . In the details panel, you can see that Angular spent over 297 ms evaluating the template of the EmployeeListComponent .

Optimizing slow computations link

Here are several techniques to remove slow computations:

• Optimizing the underlying algorithm . This is the recommended approach. If you can speed up the algorithm that is causing the problem, you can speed up the entire change detection mechanism.
• Caching using pure pipes . You can move the heavy computation to a pure pipe. Angular reevaluates a pure pipe only if it detects that its inputs have changed, compared to the previous time Angular called it.
• Using memoization . Memoization is a similar technique to pure pipes, with the difference that pure pipes preserve only the last result from the computation where memoization could store multiple results.
• Avoid repaints/reflows in lifecycle hooks . Certain operations cause the browser to either synchronously recalculate the layout of the page or re-render it. Since reflows and repaints are generally slow, you want to avoid performing them in every change detection cycle.

Pure pipes and memoization have different trade-offs. Pure pipes are an Angular built-in concept compared to memoization, which is a general software engineering practice for caching function results. The memory overhead of memoization could be significant if you invoke the heavy computation frequently with different arguments.

Resolving zone pollution link

Zone.js is a signaling mechanism that Angular uses to detect when an application state might have changed. It captures asynchronous operations like setTimeout , network requests, and event listeners. Angular schedules change detection based on signals from Zone.js

In some cases scheduled tasks or microtasks don’t make any changes in the data model, which makes running change detection unnecessary. Common examples are:

• requestAnimationFrame , setTimeout or setInterval
• Task or microtask scheduling by third-party libraries

This section covers how to identify such conditions, and how to run code outside the Angular zone to avoid unnecessary change detection calls.

Identifying unnecessary change detection calls link

You can detect unnecessary change detection calls using Angular DevTools. Often they appear as consecutive bars in the profiler’s timeline with source setTimeout , setInterval , requestAnimationFrame , or an event handler. When you have limited calls within your application of these APIs, the change detection invocation is usually caused by a third-party library.

In the image above, there is a series of change detection calls triggered by event handlers associated with an element. That’s a common challenge when using third-party, non-native Angular components, which do not alter the default behavior of NgZone .

Run tasks outside NgZone link

In such cases, you can instruct Angular to avoid calling change detection for tasks scheduled by a given piece of code using NgZone.

      
        content_copy
      
      import { Component, NgZone, OnInit } from '@angular/core';
@Component(...)
class AppComponent implements OnInit {
  constructor(private ngZone: NgZone) {}
  ngOnInit() {
    this.ngZone.runOutsideAngular(() => setInterval(pollForUpdates), 500);
  }
}
    

The preceding snippet instructs Angular to call setInterval outside the Angular Zone and skip running change detection after pollForUpdates runs.

Third-party libraries commonly trigger unnecessary change detection cycles because they weren't authored with Zone.js in mind. Avoid these extra cycles by calling library APIs outside the Angular zone:

      
        content_copy
      
      import { Component, NgZone, OnInit } from '@angular/core';
import * as Plotly from 'plotly.js-dist-min';

@Component(...)
class AppComponent implements OnInit {
  constructor(private ngZone: NgZone) {}
  ngOnInit() {
    this.ngZone.runOutsideAngular(() => {
      Plotly.newPlot('chart', data);
    });
  }
}
    

Running Plotly.newPlot('chart', data); within runOutsideAngular instructs the framework that it shouldn’t run change detection after the execution of tasks scheduled by the initialization logic.

For example, if Plotly.newPlot('chart', data) adds event listeners to a DOM element, Angular does not run change detection after the execution of their handlers.

Angular change detection and runtime optimization link

Change detection is the process through which Angular checks to see whether your application state has changed, and if any DOM needs to be updated. At a high level, Angular walks your components from top to bottom, looking for changes. Angular runs its change detection mechanism periodically so that changes to the data model are reflected in an application’s view. Change detection can be triggered either manually or through an asynchronous event (for example, a user interaction or an XMLHttpRequest completion).

Change detection is a highly optimized performant, but it can still cause slowdowns if the application runs it too frequently.

In this guide, you’ll learn how to control and optimize the change detection mechanism by skipping parts of your application and running change detection only when necessary.

Watch this video if you prefer to learn more about performance optimizations in a media format: