Angular — Component host elements

Angular creates an instance of a component for every HTML element that matches the component’s selector. The DOM element that matches a component’s selector is that component’s host element. The contents of a component’s template are rendered inside its host element.

// Component source
@Component({
  selector: 'user-profile-photo',
  template: `
    <img src="user-profile-photo.jpg" alt="Your own nice profile photo" />
  `,
})
export class UserProfilePhoto {}

<!-- Using the component -->
<h3>Your own profile photo</h3>
<user-profile-photo />
<button>Upload a new profile photo</button>

<!-- Rendered DOM -->
<h3>Your own profile photo</h3>
<user-profile-photo>
  <img src="user-profile-photo.jpg" alt="Your own nice profile photo" />
</user-profile-photo>
<button>Upload a new profile photo</button>

In the above example, <user-profile-photo> is the host element of the UserProfilePhoto component.

Binding to the host element

A component can bind properties, attributes, and events to its host element. This behaves identically to bindings on elements inside the component’s template, but instead defined with the host property in the @Component decorator:

@Component({
  ...,
  host: {
    'role': 'slider',
    '[attr.aria-valuenow]': 'value',
    '[class.active]': 'isActive()',
    '[tabIndex]': 'disabled ? -1 : 0',
    '(keydown)': 'updateValue($event)',
  },
})
export class MyCustomSlider {
  value: number = 0;
  disabled: boolean = false;
  isActive = signal(false);
  updateValue(event: KeyboardEvent) { /* ... */ }
  /* ... */
}

The @HostBinding and @HostListener decorators

You can alternatively bind to the host element by applying the @HostBinding and @HostListener decorator to class members.

Get Sithila Sihan Somaratne’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

@HostBinding lets you bind host properties and attributes to properties and getters:

@Component({
  /* ... */
})
export class MyCustomSlider {
  @HostBinding('attr.aria-valuenow')
  value: number = 0;
  @HostBinding('tabIndex')
  get tabIndex() {
    return this.disabled ? -1 : 0;
  }
  /* ... */
}

@HostListener lets you bind event listeners to the host element. The decorator accepts an event name and an optional array of arguments:

export class MyCustomSlider {
  @HostListener('keydown', ['$event'])
  updateValue(event: KeyboardEvent) {
    /* ... */
  }
}

It’s preferred using the host property over @HostBinding and @HostListener. These decorators exist exclusively for backwards compatibility.

Binding collisions

When you use a component in a template, you can add bindings to that component instance’s element. The component may also define host bindings for the same properties or attributes.

@Component({
  ...,
  host: {
    'role': 'presentation',
    '[id]': 'id',
  }
})
export class UserProfilePhoto { /* ... */ }

<user-profile-photo role="group" [id]="otherId" />

In cases like this, the following rules determine which value wins:

• If both values are static, the instance binding wins.
• If one value is static and the other dynamic, the dynamic value wins.
• If both values are dynamic, the component’s host binding wins.