Component

changeDetection?: ChangeDetectionStrategy

Defines the used change detection strategy.

When a component is instantiated, Angular creates a change detector, which is responsible for propagating the component's bindings.

The changeDetection property defines, whether the change detection will be checked every time or only when the component tells it to do so.

viewProviders?: Provider[]

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

Simple Example

Here is an example of a class that can be injected:

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 {
}

moduleId?: string

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

Simple Example

@Directive({
  selector: 'someDir',
  moduleId: module.id
})
class SomeDir {
}

templateUrl?: string

Specifies a template URL for an Angular component.

Only one of templateUrl or template can be defined per View.

template?: string

Specifies an inline template for an Angular component.

Only one of templateUrl or template can be defined per Component.

styleUrls?: string[]

Specifies stylesheet URLs for an Angular component.

styles?: string[]

Specifies inline stylesheets for an Angular component.

animations?: any[]

Animations are defined on components via an animation-like DSL. This DSL approach to describing animations allows for a flexibility that both benefits developers and the framework.

Animations work by listening on state changes that occur on an element within the template. When a state change occurs, Angular can then take advantage and animate the arc in between. This works similar to how CSS transitions work, however, by having a programmatic DSL, animations are not limited to environments that are DOM-specific. (Angular can also perform optimizations behind the scenes to make animations more performant.)

For animations to be available for use, animation state changes are placed within animation triggers which are housed inside of the animations annotation metadata. Within a trigger both state and transition entries can be placed.

@Component({
  selector: 'animation-cmp',
  templateUrl: 'animation-cmp.html',
  animations: [
    // this here is our animation trigger that
    // will contain our state change animations.
    trigger('myTriggerName', [
      // the styles defined for the `on` and `off`
      // states declared below are persisted on the
      // element once the animation completes.
      state('on', style({ opacity: 1 }),
      state('off', style({ opacity: 0 }),

      // this here is our animation that kicks off when
      // this state change jump is true
      transition('on => off', [
        animate("1s")
      ])
    ])
  ]
})

As depicted in the code above, a group of related animation states are all contained within an animation trigger (the code example above called the trigger myTriggerName). When a trigger is created then it can be bound onto an element within the component's template via a property prefixed by an @ symbol followed by trigger name and an expression that is used to determine the state value for that trigger.

<!-- animation-cmp.html -->
<div @myTriggerName="expression">...</div>

For state changes to be executed, the expression value must change value from its existing value to something that we have set an animation to animate on (in the example above we are listening to a change of state between on and off). The expression value attached to the trigger must be something that can be evaluated with the template/component context.

DSL Animation Functions

Please visit each of the animation DSL functions listed below to gain a better understanding of how and why they are used for crafting animations in Angular:

• trigger()
• state()
• transition()
• group()
• sequence()
• style()
• animate()
• keyframes()

encapsulation?: ViewEncapsulation

Specifies how the template and the styles should be encapsulated:

• `ViewEncapsulation.Native`

  to use shadow roots - only works if natively available on the platform,

• `ViewEncapsulation.Emulated`

  to use shimmed CSS that emulates the native behavior,

• `ViewEncapsulation.None`

  to use global CSS without any encapsulation.

When no encapsulation is defined for the component, the default value from the CompilerOptions is used. The default is ViewEncapsulation.Emulated}. Provide a new CompilerOptions to override this value.

If the encapsulation is set to ViewEncapsulation.Emulated and the component has no styles nor styleUrls the encapsulation will automatically be switched to ViewEncapsulation.None.

interpolation?: [string, string]

Overrides the default encapsulation start and end delimiters (respectively {{ and }})

entryComponents?: Array<Type<any> | any[]>

Defines the components that should be compiled as well when this component is defined. For each components listed here, Angular will create a ComponentFactory and store it in the ComponentFactoryResolver.

preserveWhitespaces?: boolean

If Component.preserveWhitespaces is set to false potentially superfluous whitespace characters (ones matching the \s character class in JavaScript regular expressions) will be removed from a compiled template. This can greatly reduce AOT-generated code size as well as speed up view creation.

Current implementation works according to the following rules:

• all whitespaces at the beginning and the end of a template are removed (trimmed);
• text nodes consisting of whitespaces only are removed (ex.: <button>Action 1</button> <button>Action 2</button> will be converted to <button>Action 1</button><button>Action 2</button> (no whitespaces between buttons);
• series of whitespaces in text nodes are replaced with one space (ex.: <span>\n some text\n</span> will be converted to <span> some text </span>);
• text nodes are left as-is inside HTML tags where whitespaces are significant (ex. <pre>, <textarea>).

Described transformations can (potentially) influence DOM nodes layout so the preserveWhitespaces option is true be default (no whitespace removal). In Angular 5 you need to opt-in for whitespace removal (but we might revisit the default setting in Angular 6 or later). If you want to change the default setting for all components in your application you can use the preserveWhitespaces option of the AOT compiler.

Even if you decide to opt-in for whitespace removal there are ways of preserving whitespaces in certain fragments of a template. You can either exclude entire DOM sub-tree by using the ngPreserveWhitespaces attribute, ex.:

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

Alternatively you can force a space to be preserved in a text node by using the &ngsp; pseudo-entity. &ngsp; will be replaced with a space character by Angular's template compiler, ex.:

<a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>

will be compiled to the equivalent of:

<a>Spaces</a> <a>between</a> <a>links.</a>

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

<a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>

would be equivalent to:

<a>before</a> <a>after</a>

The &ngsp; pseudo-entity is useful for forcing presence of one space (a text node having &ngsp; pseudo-entities will never be removed), but it is not meant to mark sequences of whitespace characters. The previously described ngPreserveWhitespaces attribute is more useful for preserving sequences of whitespace characters.