@angular/core

Component

decorator

Decorator that marks a class as an Angular component and provides configuration metadata that determines how the component should be processed, instantiated, and used at runtime.

class Component {
}

Decorator that marks a class as an Angular component and provides configuration metadata that determines how the component should be processed, instantiated, and used at runtime.

Components are the most basic UI building block of an Angular app. An Angular app contains a tree of Angular components.

Angular components are a subset of directives, always associated with a template. Unlike other directives, only one component can be instantiated for a given element in a template.

A component must belong to an NgModule in order for it to be available to another component or application. To make it a member of an NgModule, list it in the declarations field of the NgModule metadata.

Note that, in addition to these options for configuring a directive, you can control a component's runtime behavior by implementing life-cycle hooks. For more information, see the Lifecycle Hooks guide.

Setting component inputs

The following example creates a component with two data-bound properties, specified by the inputs value.

Setting component outputs

The following example shows two event emitters that emit on an interval. One emits an output every second, while the other emits every five seconds.

Injecting a class with a view provider

The following simple example injects a class into a component using the view provider specified in component metadata:

          
            class Greeter {   greet(name:string) {     return 'Hello ' + name + '!';   }}@Directive({  selector: 'needs-greeter'})class NeedsGreeter {  greeter:Greeter;  constructor(greeter:Greeter) {    this.greeter = greeter;  }}@Component({  selector: 'greet',  viewProviders: [    Greeter  ],  template: `<needs-greeter></needs-greeter>`})class HelloWorld {}

Preserving whitespace

Removing whitespace can greatly reduce AOT-generated code size and speed up view creation. As of Angular 6, the default for preserveWhitespaces is false (whitespace is removed). To change the default setting for all components in your application, set the preserveWhitespaces option of the AOT compiler.

By default, the AOT compiler removes whitespace characters as follows:

Trims all whitespaces at the beginning and the end of a template.
Removes whitespace-only text nodes. For example,

          
            <button>Action 1</button>  <button>Action 2</button>

becomes:

          
            <button>Action 1</button><button>Action 2</button>

Replaces a series of whitespace characters in text nodes with a single space. For example, <span>\n some text\n</span> becomes <span> some text </span>.
Does NOT alter text nodes inside HTML tags such as <pre> or <textarea>, where whitespace characters are significant.

Note that these transformations can influence DOM nodes layout, although impact should be minimal.

You can override the default behavior to preserve whitespace characters in certain fragments of a template. For example, you can exclude an entire DOM sub-tree by using the ngPreserveWhitespaces attribute:

          
            <div ngPreserveWhitespaces>    whitespaces are preserved here    <span>    and here </span></div>

You can force a single space to be preserved in a text node by using &ngsp;, which is replaced with a space character by Angular's template compiler:

          
            <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a><!-- compiled to be equivalent to: <a>Spaces</a> <a>between</a> <a>links.</a>  -->

Note that sequences of &ngsp; are still collapsed to just one space character when the preserveWhitespaces option is set to false.

          
            <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a><!-- compiled to be equivalent to: <a>before</a> <a>after</a> -->

To preserve sequences of whitespace characters, use the ngPreserveWhitespaces attribute.

changeDetection

ChangeDetectionStrategy

The change-detection strategy to use for this component.

When a component is instantiated, Angular creates a change detector, which is responsible for propagating the component's bindings. The strategy is one of:

ChangeDetectionStrategy#OnPush sets the strategy to CheckOnce (on demand).
ChangeDetectionStrategy#Default sets the strategy to CheckAlways.

viewProviders

Provider[]

Defines the set of injectable objects that are visible to its view DOM children. See example.

moduleId

string

@deprecated

This option does not have any effect. Will be removed in Angular v17.

The module ID of the module that contains the component. The component must be able to resolve relative URLs for templates and styles. SystemJS exposes the __moduleName variable within each module. In CommonJS, this can be set to module.id.

templateUrl

string

The relative path or absolute URL of a template file for an Angular component. If provided, do not supply an inline template using template.

template

string

An inline template for an Angular component. If provided, do not supply a template file using templateUrl.

styleUrl

string

One relative paths or an absolute URL for files containing CSS stylesheet to use in this component.

styleUrls

string[]

Relative paths or absolute URLs for files containing CSS stylesheets to use in this component.

styles

string | string[]

One or more inline CSS stylesheets to use in this component.

animations

any[]

One or more animation trigger() calls, containing state() and transition() definitions. See the Animations guide and animations API documentation.

encapsulation

ViewEncapsulation

An encapsulation policy for the component's styling. Possible values:

ViewEncapsulation.Emulated: Apply modified component styles in order to emulate a native Shadow DOM CSS encapsulation behavior.
ViewEncapsulation.None: Apply component styles globally without any sort of encapsulation.
ViewEncapsulation.ShadowDom: Use the browser's native Shadow DOM API to encapsulate styles.

If not supplied, the value is taken from the CompilerOptions which defaults to ViewEncapsulation.Emulated.

If the policy is ViewEncapsulation.Emulated and the component has no Component#styles styles nor {@link Component#styleUrls styleUrls}, the policy is automatically switched to ViewEncapsulation.None.

interpolation

[string, string]

@deprecated

use Angular's default interpolation delimiters instead.

Overrides the default interpolation start and end delimiters ({{ and }}).

preserveWhitespaces

boolean

True to preserve or false to remove potentially superfluous whitespace characters from the compiled template. Whitespace characters are those matching the \s character class in JavaScript regular expressions. Default is false, unless overridden in compiler options.

standalone

boolean

Angular components marked as standalone do not need to be declared in an NgModule. Such components directly manage their own template dependencies (components, directives, and pipes used in a template) via the imports property.

More information about standalone components, directives, and pipes can be found in this guide.

imports

(readonly any[] | Type<any>)[]

The imports property specifies the standalone component's template dependencies — those directives, components, and pipes that can be used within its template. Standalone components can import other standalone components, directives, and pipes as well as existing NgModules.

This property is only available for standalone components - specifying it for components declared in an NgModule generates a compilation error.

More information about standalone components, directives, and pipes can be found in this guide.

schemas

SchemaMetadata[]

The set of schemas that declare elements to be allowed in a standalone component. Elements and properties that are neither Angular components nor directives must be declared in a schema.

This property is only available for standalone components - specifying it for components declared in an NgModule generates a compilation error.

More information about standalone components, directives, and pipes can be found in this guide.

selector

string

The CSS selector that identifies this directive in a template and triggers instantiation of the directive.

Declare as one of the following:

element-name: Select by element name.
.class: Select by class name.
[attribute]: Select by attribute name.
[attribute=value]: Select by attribute name and value.
:not(sub_selector): Select only if the element does not match the sub_selector.
selector1, selector2: Select if either selector1 or selector2 matches.

Angular only allows directives to apply on CSS selectors that do not cross element boundaries.

For the following template HTML, a directive with an input[type=text] selector, would be instantiated only on the <input type="text"> element.

          
            <form>  <input type="text">  <input type="radio"><form>

inputs

(string | { name: string; alias?: string; required?: boolean; transform?: (value: any) => any; })[]

Enumerates the set of data-bound input properties for a directive

Angular automatically updates input properties during change detection. The inputs property accepts either strings or object literals that configure the directive properties that should be exposed as inputs.

When an object literal is passed in, the name property indicates which property on the class the input should write to, while the alias determines the name under which the input will be available in template bindings. The required property indicates that the input is required which will trigger a compile-time error if it isn't passed in when the directive is used.

When a string is passed into the inputs array, it can have a format of 'name' or 'name: alias' where name is the property on the class that the directive should write to, while the alias determines the name under which the input will be available in template bindings. String-based input definitions are assumed to be optional.

outputs

string[]

Enumerates the set of event-bound output properties.

When an output property emits an event, an event handler attached to that event in the template is invoked.

The outputs property defines a set of directiveProperty to alias configuration:

directiveProperty specifies the component property that emits events.
alias specifies the DOM property the event handler is attached to.

providers

Provider[]

Configures the injector of this directive or component with a token that maps to a provider of a dependency.

exportAs

string

Defines the name that can be used in the template to assign this directive to a variable.

queries

{ [key: string]: any; }

Configures the queries that will be injected into the directive.

Content queries are set before the ngAfterContentInit callback is called. View queries are set before the ngAfterViewInit callback is called.

host

{ [key: string]: string; }

Maps class properties to host element bindings for properties, attributes, and events, using a set of key-value pairs.

Angular automatically checks host property bindings during change detection. If a binding changes, Angular updates the directive's host element.

When the key is a property of the host element, the property value is propagated to the specified DOM property.

When the key is a static attribute in the DOM, the attribute value is propagated to the specified property in the host element.

For event handling:

The key is the DOM event that the directive listens to. To listen to global events, add the target to the event name. The target can be window, document or body.
The value is the statement to execute when the event occurs. If the statement evaluates to false, then preventDefault is applied on the DOM event. A handler method can refer to the $event local variable.

jit

true

When present, this directive/component is ignored by the AOT compiler. It remains in distributed code, and the JIT compiler attempts to compile it at run time, in the browser. To ensure the correct behavior, the app must import @angular/compiler.

hostDirectives

(Type<unknown> | { directive: Type<unknown>; inputs?: string[]; outputs?: string[]; })[]

Standalone directives that should be applied to the host whenever the directive is matched. By default, none of the inputs or outputs of the host directives will be available on the host, unless they are specified in the inputs or outputs properties.

You can additionally alias inputs and outputs by putting a colon and the alias after the original input or output name. For example, if a directive applied via hostDirectives defines an input named menuDisabled, you can alias this to disabled by adding 'menuDisabled: disabled' as an entry to inputs.