This is the archived documentation for Angular v6. Please visit angular.io to see documentation for the current version of Angular.
API > @angular/core

Directive

Marks a class as an Angular directive. You can define your own directives to attach custom behavior to elements in the DOM. The options provide configuration metadata that determines how the directive should be processed, instantiated and used at runtime.

See more...

OptionDescription
selector

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

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

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.
providers

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

The name or names that can be used in the template to assign this directive to a variable. For multiple names, use a comma-separated string.
queries

Configures the queries that will be injected into the directive.
jit

If true, this directive/component will be skipped by the AOT compiler and so will always be compiled using JIT.
host

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

Subclasses

Description

Directive classes, like component classes, can implement life-cycle hooks to influence their configuration and behavior.

Options

selector

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

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> 
      
      <form>
  <input type="text">
  <input type="radio">
<form>

inputs

Enumerates the set of data-bound input properties for a directive
inputs: string[] 
      
      inputs: string[]

Angular automatically updates input properties during change detection. The inputs property defines a set of directiveProperty to bindingProperty configuration:

  • directiveProperty specifies the component property where the value is written.
  • bindingProperty specifies the DOM property where the value is read from.

When bindingProperty is not provided, it is assumed to be equal to directiveProperty.

Example

The following example creates a component with two data-bound properties.

@Component({ selector: 'bank-account', inputs: ['bankName', 'id: account-id'], template: ` Bank Name: {{bankName}} Account Id: {{id}} ` }) class BankAccount { bankName: string; id: string; 
      
      @Component({
  selector: 'bank-account',
  inputs: ['bankName', 'id: account-id'],
  template: `
    Bank Name: {{bankName}}
    Account Id: {{id}}
  `
})
class BankAccount {
  bankName: string;
  id: string;

outputs

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.
outputs: string[] 
      
      outputs: string[]

Each output property maps a directiveProperty to a bindingProperty:

  • directiveProperty specifies the component property that emits events.
  • bindingProperty specifies the HTML attribute the event handler is attached to.

providers

Configures the injector of this directive or component with a token that maps to a provider of a dependency.
providers: Provider[] 
      
      providers: Provider[]

exportAs

The name or names that can be used in the template to assign this directive to a variable. For multiple names, use a comma-separated string.
exportAs: string 
      
      exportAs: string

queries

Configures the queries that will be injected into the directive.
queries: { [key: string]: any; } 
      
      queries: {
    [key: string]: any;
}

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

jit

If true, this directive/component will be skipped by the AOT compiler and so will always be compiled using JIT.
jit: true 
      
      jit: true

This exists to support future Ivy work and has no effect currently.

host

Maps class properties to host element bindings for properties, attributes, and events, using a set of key-value pairs.
host: { [key: string]: string; } 
      
      host: {
    [key: string]: string;
}

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 the 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 evalueates to false, then preventDefault is applied on the DOM event. A handler method can refer to the $event local variable.

Usage notes

To define a directive, mark the class with the decorator and provide metadata.

import {Directive} from '@angular/core'; @Directive({ selector: 'my-directive', }) export class MyDirective { ... } 
      
      import {Directive} from '@angular/core';

@Directive({
  selector: 'my-directive',
})
export class MyDirective {
...
}

Declaring directives

Directives are declarables. They must be declared by an NgModule in order to be usable in an app.

A directive must belong to exactly one NgModule. Do not re-declare a directive imported from another module. List the directive class in the declarations field of an NgModule.

declarations: [ AppComponent, MyDirective ], 
      
      declarations: [
 AppComponent,
 MyDirective
],