An NgModule describes how the application parts fit together.
Every application has at least one Angular module, the
root
module, which must be present for bootstrapping the application on launch.
By convention and by default, this NgModule is named
AppModule
.
When you use the Angular CLI command
ng new
to generate an app, the default
AppModule
looks like the following:
/* JavaScript imports */import{BrowserModule} from '@angular/platform-browser';import{NgModule} from '@angular/core';import{AppComponent} from './app.component';/* the AppModule class with the @NgModule decorator */@NgModule({
declarations:[AppComponent],
imports:[BrowserModule],
providers:[],
bootstrap:[AppComponent]})exportclassAppModule{}
After the import statements is a class with the
@NgModule
decorator.
The
@NgModule
decorator identifies
AppModule
as an
NgModule
class.
@NgModule
takes a metadata object that tells Angular how to compile and launch the application.
metadata object
Details
declarations
This application's lone component.
imports
Import
BrowserModule
to have browser-specific services such as DOM rendering, sanitization, and location.
providers
The service providers.
bootstrap
The
root
component that Angular creates and inserts into the
index.html
host web page.
The default application created by the Angular CLI only has one component,
AppComponent
, so it is in both the
declarations
and the
bootstrap
arrays.
The
declarations
array
link
The module's
declarations
array tells Angular which components belong to that module.
As you create more components, add them to
declarations
.
You must declare every component in exactly one
NgModule
class.
If you use a component without declaring it, Angular returns an error message.
The
declarations
array only takes declarables. Declarables are components, directives, and pipes.
All of a module's declarables must be in the
declarations
array.
Declarables must belong to exactly one module. The compiler emits an error if you try to declare the same class in more than one module.
These declared classes are visible within the module but invisible to components in a different module, unless they are exported from this module and the other module imports this one.
An example of what goes into a declarations array follows:
A declarable can only belong to one module, so only declare it in one
@NgModule
.
When you need it elsewhere, import the module that contains the declarable you need.
Using directives with
@NgModule
link
Use the
declarations
array for directives.
To use a directive, component, or pipe in a module, you must do a few things:
Export it from the file where you wrote it.
Import it into the appropriate module.
Declare it in the
@NgModule
declarations
array.
Those three steps look like the following. In the file where you create your directive, export it.
The following example, named
ItemDirective
is the default directive structure that the CLI generates in its own file,
item.directive.ts
:
The key point here is that you have to export it, so that you can import it elsewhere.
Next, import it into the
NgModule
, in this example
app.module.ts
, with a JavaScript import statement:
src/app/app.module.ts
import{ItemDirective}from'./item.directive';
And in the same file, add it to the
@NgModule
declarations
array:
src/app/app.module.ts
declarations:[AppComponent,ItemDirective],
Now you could use your
ItemDirective
in a component.
This example uses
AppModule
, but you'd do it the same way for a feature module.
For more about directives, see Attribute Directives and Structural Directives.
You'd also use the same technique for pipes and components.
Remember, components, directives, and pipes belong to one module only.
You only need to declare them once in your application because you share them by importing the necessary modules.
This saves you time and helps keep your application lean.
The
imports
array
link
The module's
imports
array appears exclusively in the
@NgModule
metadata object.
It tells Angular about other NgModules that this particular module needs to function properly.
This list of modules are those that export components, directives, or pipes that component templates in this module reference.
In this case, the component is
AppComponent
, which references components, directives, or pipes in
BrowserModule
,
FormsModule
, or
HttpClientModule
.
A component template can reference another component, directive, or pipe when the referenced class is declared in this module, or the class was imported from another module.
The
providers
array
link
The providers array is where you list the services the application needs.
When you list services here, they are available app-wide.
You can scope them when using feature modules and lazy loading.
For more information, see Providers.
The
bootstrap
array
link
The application launches by bootstrapping the root
AppModule
, which is also referred to as an
entryComponent
.
Among other things, the bootstrapping process creates the component(s) listed in the
bootstrap
array and inserts each one into the browser DOM.
Each bootstrapped component is the base of its own tree of components.
Inserting a bootstrapped component usually triggers a cascade of component creations that fill out that tree.
While you can put more than one component tree on a host web page, most applications have only one component tree and bootstrap a single root component.
This one root component is usually called
AppComponent
and is in the root module's
bootstrap
array.
In a situation where you want to bootstrap a component based on an API response,
or you want to mount the
AppComponent
in a different DOM node that doesn't match the component selector, please refer to
ApplicationRef.bootstrap()
documentation.
More about Angular Modules
link
For more on NgModules you're likely to see frequently in applications, see Frequently Used Modules.
Angular supports most recent browsers.
This includes the following specific versions:
Browser
Supported versions
Chrome
latest
Firefox
latest and extended support release (ESR)
Edge
2 most recent major versions
Safari
2 most recent major versions
iOS
2 most recent major versions
Android
2 most recent major versions
Angular's continuous integration process runs unit tests of the framework on all of these browsers for every pull request, using Sauce Labs.
Polyfills
link
Angular is built on the latest standards of the web platform.
Targeting such a wide range of browsers is challenging because they do not support all features of modern browsers.
You compensate by loading polyfill scripts ("polyfills") for the browsers that you must support.
See instructions on how to include polyfills into your project below.
The suggested polyfills are the ones that run full Angular applications.
You might need additional polyfills to support features not covered by this list.
NOTE
:
Polyfills cannot magically transform an old, slow browser into a modern, fast one.
Enabling polyfills with CLI projects
link
The Angular CLI provides support for polyfills.
If you are not using the CLI to create your projects, see Polyfill instructions for non-CLI users.
The
polyfills
options of the browser and test builder can be a full path for a file (Example:
src/polyfills.ts
) or,
relative to the current workspace or module specifier (Example:
zone.js
).
If you create a TypeScript file, make sure to include it in the
files
property of your
tsconfig
file.
If you are not using the CLI, add your polyfill scripts directly to the host web page (
index.html
).
For example:
src/index.html
<!-- pre-zone polyfills --><scriptsrc="node_modules/core-js/client/shim.min.js"></script><script>/**
* you can configure some zone flags which can disable zone interception for some
* asynchronous activities to improve startup performance - use these options only
* if you know what you are doing as it could result in hard to trace down bugs.
*/// __Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame// __Zone_disable_on_property = true; // disable patch onProperty such as onclick// __zone_symbol__UNPATCHED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames/*
* in Edge developer tools, the addEventListener will also be wrapped by zone.js
* with the following flag, it will bypass `zone.js` patch for Edge.
*/// __Zone_enable_cross_context_check = true;</script><!-- zone.js required by Angular --><scriptsrc="node_modules/zone.js/bundles/zone.umd.js"></script><!-- application polyfills -->
This page discusses build-specific configuration options for Angular projects.
Configuring application environments
link
You can define different named build configurations for your project, such as
staging
and
production
, with different defaults.
Each named configuration can have defaults for any of the options that apply to the various builder targets, such as
build
,
serve
, and
test
.
The Angular CLI
build
,
serve
, and
test
commands can then replace files with appropriate versions for your intended target environment.
Configure environment-specific defaults
link
A project's
src/environments/
folder contains the base configuration file,
environment.ts
, which provides a default environment.
You can add override defaults for additional environments, such as production and staging, in target-specific configuration files.
For example:
myProject/src/environments
environment.ts
environment.prod.ts
environment.staging.ts
The base file
environment.ts
, contains the default environment settings.
For example:
exportconst environment ={
production:false};
The
build
command uses this as the build target when no environment is specified.
You can add further variables, either as additional properties on the environment object, or as separate objects.
For example, the following adds a default for a variable to the default environment:
You can add target-specific configuration files, such as
environment.prod.ts
.
The following content sets default values for the production build target:
Using environment-specific variables in your app
link
The following application structure configures build targets for production and staging environments:
src
app
app.component.html
app.component.ts
environments
environment.ts
environment.prod.ts
environment.staging.ts
To use the environment configurations you have defined, your components must import the original environments file:
import{ environment } from './../environments/environment';
This ensures that the build and serve commands can find the configurations for specific build targets.
The following code in the component file (
app.component.ts
) uses an environment variable defined in the configuration files.
import{Component} from '@angular/core';import{ environment } from './../environments/environment';@Component({
selector:'app-root',
templateUrl:'./app.component.html',
styleUrls:['./app.component.css']})exportclassAppComponent{constructor(){
console.log(environment.production);// Logs false for default environment}
title ='app works!';}
Configure target-specific file replacements
link
The main CLI configuration file,
angular.json
, contains a
fileReplacements
section in the configuration for each build target, which lets you replace any file in the TypeScript program with a target-specific version of that file.
This is useful for including target-specific code or variables in a build that targets a specific environment, such as production or staging.
By default no files are replaced.
You can add file replacements for specific build targets.
For example:
This means that when you build your production configuration with
ng build --configuration production
, the
src/environments/environment.ts
file is replaced with the target-specific version of the file,
src/environments/environment.prod.ts
.
You can add additional configurations as required.
To add a staging environment, create a copy of
src/environments/environment.ts
called
src/environments/environment.staging.ts
, then add a
staging
configuration to
angular.json
:
You can add more configuration options to this target environment as well.
Any option that your build supports can be overridden in a build target configuration.
To build using the staging configuration, run the following command:
ng build --configuration=staging
You can also configure the
serve
command to use the targeted build configuration if you add it to the "serve:configurations" section of
angular.json
:
As applications grow in functionality, they also grow in size.
The CLI lets you set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define.
Define your size boundaries in the CLI configuration file,
angular.json
, in a
budgets
section for each configured environment.
You can specify size budgets for the entire app, and for particular parts.
Each budget entry configures a budget of a given type.
Specify size values in the following formats:
Size value
Details
123
or
123b
Size in bytes.
123kb
Size in kilobytes.
123mb
Size in megabytes.
12%
Percentage of size relative to baseline. (Not valid for baseline values.)
When you configure a budget, the build system warns or reports an error when a given part of the application reaches or exceeds a boundary size that you set.
Each budget entry is a JSON object with the following properties:
Property
Value
type
The type of budget. One of:
Value
Details
bundle
The size of a specific bundle.
initial
The size of JavaScript needed for bootstrapping the application. Defaults to warning at 500kb and erroring at 1mb.
allScript
The size of all scripts.
all
The size of the entire application.
anyComponentStyle
This size of any one component stylesheet. Defaults to warning at 2kb and erroring at 4kb.
anyScript
The size of any one script.
any
The size of any file.
name
The name of the bundle (for
type=bundle
).
baseline
The baseline size for comparison.
maximumWarning
The maximum threshold for warning relative to the baseline.
maximumError
The maximum threshold for error relative to the baseline.
minimumWarning
The minimum threshold for warning relative to the baseline.
minimumError
The minimum threshold for error relative to the baseline.
warning
The threshold for warning relative to the baseline (min & max).
error
The threshold for error relative to the baseline (min & max).
Configuring CommonJS dependencies
link
It is recommended that you avoid depending on CommonJS modules in your Angular applications.
Depending on CommonJS modules can prevent bundlers and minifiers from optimizing your application, which results in larger bundle sizes.
Instead, it is recommended that you use ECMAScript modules in your entire application.
For more information, see How CommonJS is making your bundles larger.
The Angular CLI outputs warnings if it detects that your browser application depends on CommonJS modules.
To disable these warnings, add the CommonJS module name to
allowedCommonJsDependencies
option in the
build
options located in
angular.json
file.
The Angular CLI uses Browserslist to ensure compatibility with different browser versions. Autoprefixer is used for CSS vendor prefixing and @babel/preset-env for JavaScript syntax transformations.
Internally, the Angular CLI uses the below
browserslist
configuration which matches the browsers that are supported by Angular.
last1Chrome version
last1Firefox version
last2Edge major versions
last2Safari major versions
last2 iOS major versions
Firefox ESR
To override the internal configuration, add a new file named
.browserslistrc
, to the project directory, that specifies the browsers you want to support:
last1Chrome version
last1Firefox version
See the browserslist repository for more examples of how to target specific browsers and versions.
Use browsersl.ist to display compatible browsers for a
browserslist
query.
Proxying to a backend server
link
Use the proxying support in the
webpack
development server to divert certain URLs to a backend server, by passing a file to the
--proxy-config
build option.
For example, to divert all calls for
http://localhost:4200/api
to a server running on
http://localhost:3000/api
, take the following steps.
Create a file
proxy.conf.json
in your project's
src/
folder.
To run the development server with this proxy configuration, call
ng serve
.
Edit the proxy configuration file to add configuration options; following are some examples.
For a description of all options, see webpack DevServer documentation.
NOTE
:
If you edit the proxy configuration file, you must relaunch the
ng serve
process to make your changes effective.
Rewrite the URL path
link
The
pathRewrite
proxy configuration option lets you rewrite the URL path at run time.
For example, specify the following
pathRewrite
value to the proxy configuration to remove "api" from the end of a path.
If you need to optionally bypass the proxy, or dynamically change the request before it's sent, add the bypass option, as shown in this JavaScript example.
If you work behind a corporate proxy, the backend cannot directly proxy calls to any URL outside your local network.
In this case, you can configure the backend proxy to redirect calls through your corporate proxy using an agent:
npm install --save-dev https-proxy-agent
When you define an environment variable
http_proxy
or
HTTP_PROXY
, an agent is automatically added to pass calls through your corporate proxy when running
npm start
.
Use the following content in the JavaScript configuration file.
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.
See the
live example
/ download example
for a working example containing the code snippets in this guide.
The different types of Angular directives are as follows:
Directive Types
Details
Components
Used with a template. This type of directive is the most common directive type.
Attribute directives
Change the appearance or behavior of an element, component, or another directive.
Structural directives
Change the DOM layout by adding and removing DOM elements.
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:
Common directives
Details
NgClass
Adds and removes a set of CSS classes.
NgStyle
Adds and removes a set of HTML styles.
NgModel
Adds two-way data binding to an HTML form element.
Built-in directives use only public APIs.
They do not have special access to any private APIs that other directives can't access.
Adding and removing classes with
NgClass
link
Add or remove multiple CSS classes simultaneously with
ngClass
.
To add or remove a
single
class, use class binding rather than
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>
.
src/app/app.component.html
<!-- toggle the "special" class on/off with a property --><div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>
Using
NgClass
with a method
link
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
currentClasses:Record<string,boolean>={};/* . . . */
setCurrentClasses(){// CSS classes: added/removed per current state of component propertiesthis.currentClasses ={
saveable:this.canSave,
modified:!this.isUnchanged,
special:this.isSpecial
};}
In the template, add the
ngClass
property binding to
currentClasses
to set the element's classes:
src/app/app.component.html
<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.
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
currentStyles:Record<string,string>={};/* . . . */
setCurrentStyles(){// CSS styles: set per current state of component propertiesthis.currentStyles ={'font-style':this.canSave ?'italic':'normal','font-weight':!this.isUnchanged ?'bold':'normal','font-size':this.isSpecial ?'24px':'12px'};}
To set the element's styles, add an
ngStyle
property binding to
currentStyles
.
src/app/app.component.html
<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.
Import
FormsModule
and add it to the NgModule's
imports
list.
src/app/app.module.ts (FormsModule import)
import{FormsModule}from'@angular/forms';// <--- JavaScript import from Angular/* . . . */@NgModule({/* . . . */
imports:[BrowserModule,FormsModule// <--- import into the NgModule],/* . . . */})exportclassAppModule{}
Add an
[(ngModel)]
binding on an HTML
<form>
element and set it equal to the property, here
name
.
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:
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.
When you write an Angular component, you don't need a value accessor or
NgModel
if you name the value and event properties according to Angular's two-way binding syntax.
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:
Common built-in structural directives
Details
NgIf
Conditionally creates or disposes of subviews from the template.
NgFor
Repeat a node for each item in a list.
NgSwitch
A set of directives that switch among alternative views.
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.
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
.
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
.
Use the
NgFor
directive to present a list of items.
Define a block of HTML that determines how Angular renders a single item.
To list your items, assign the shorthand
let item of items
to
*ngFor
.
src/app/app.component.html
<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>
.
src/app/app.component.html
<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.
src/app/app.component.html
<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.
src/app/app.component.html
<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.
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
trackByItems(index: number, item:Item): number {return item.id;}
In the shorthand expression, set
trackBy
to the
trackByItems()
method.
src/app/app.component.html
<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>
.
src/app/app.component.html (ngif-ngcontainer)
<p>
I turned the corner
<ng-container *ngIf="hero">
and saw {{hero.name}}. I waved
</ng-container>
and continued on my way.
</p>
Import the
ngModel
directive from
FormsModule
.
Add
FormsModule
to the imports section of the relevant Angular module.
To conditionally exclude an
<option>
, wrap the
<option>
in an
<ng-container>
.
src/app/app.component.html (select-ngcontainer)
<div>
Pick your favorite hero
(<label><inputtype="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:
NgSwitch
directives
Details
NgSwitch
An attribute directive that changes the behavior of its companion directives.
NgSwitchCase
Structural directive that adds its element to the DOM when its bound value equals the switch value and removes its bound value when it doesn't equal the switch value.
NgSwitchDefault
Structural directive that adds its element to the DOM when there is no selected
NgSwitchCase
.
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.
Bind to
*ngSwitchCase
and
*ngSwitchDefault
on the elements for the cases.
In the parent component, define
currentItem
, to use it in the
[ngSwitch]
expression.
src/app/app.component.ts
currentItem!:Item;
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
.
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.
src/app/app.component.html
<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.
An event is handled by a component with default change detection
An event is handled by a component with OnPush
An event is handled by a descendant of a component with OnPush
New inputs to component with OnPush
Edge cases
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:
import{ChangeDetectionStrategy,Component} from '@angular/core';@Component({
changeDetection:ChangeDetectionStrategy.OnPush,})exportclassMyComponent{}
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.