Skip to content

Host Binding and Host Listening

Angular creates a component instance for every DOM element matching its selector, and that element is the component’s host element. The template renders inside it:

@Component({
selector: 'profile-photo',
template: `<img src="profile-photo.jpg" alt="Your profile photo" />`,
})
export class ProfilePhoto {}
<!-- Rendered DOM -->
<profile-photo>
<img src="profile-photo.jpg" alt="Your profile photo" />
</profile-photo>

The host element is real, it is in the DOM, and it is often the element that most needs an ARIA role, a class, or an event listener. Host bindings are how a component controls it.

@Component({
selector: 'custom-slider',
host: {
'role': 'slider',
'[attr.aria-valuenow]': 'value()',
'[attr.aria-disabled]': 'disabled()',
'[class.active]': 'isActive()',
'[style.background]': `hasError() ? 'red' : 'green'`,
'[tabIndex]': 'disabled() ? -1 : 0',
'(keydown)': 'onKeydown($event)',
},
})
export class CustomSlider { /* ... */ }

The syntax is exactly template binding syntax, applied to the host:

Form Binds
'role': 'slider' A static attribute
'[attr.aria-valuenow]' An attribute, dynamically
'[class.active]' A single CSS class
'[style.background]' A single style property
'[tabIndex]' A DOM property
'(keydown)' An event listener

Values are expressions evaluated against the component instance, so signals work naturally — '[class.active]': 'isActive()'. Host property bindings are a reactive context, so a signal read there is tracked like one in a template.

Global event targets: prefix an event with document:, window: or body: to listen outside the host. Those are the only three supported targets.

host: {
'(document:click)': 'onDocumentClick($event)',
'(window:resize)': 'onResize()',
}

Angular removes these listeners when the component is destroyed, which is a real advantage over adding them by hand and forgetting to remove them.

[tabIndex] sets the DOM property; [attr.tabindex] sets the HTML attribute. Most of the time the property is what you want, because it is typed and it is what the browser actually consults.

ARIA attributes are a special case, and a convenient one. The compiler recognises any binding whose name begins with aria- and compiles it as an attribute binding, so both forms work and mean the same thing:

host: {
'[aria-valuenow]': 'value()', // recognised as an ARIA attribute
'[attr.aria-valuenow]': 'value()', // explicit, equally correct
}

The official examples use the explicit attr. form; the shorter form is available and reads better in a long host block. Pick one and be consistent.

role is not aria--prefixed, so it does not get that treatment — use a static 'role': 'slider' or '[attr.role]'. data-* attributes likewise need attr..

One useful behaviour that applies to attribute bindings generally: binding to null removes the attribute, which is how you express “this only applies sometimes”:

host: { '[attr.aria-describedby]': 'hasError() ? errorId : null' }

A consumer can bind to the same property on your component’s element that you bind in host:

host: { 'role': 'presentation', '[id]': 'id()' }
<profile-photo role="group" [id]="otherId" />

The resolution rules:

  • Both static → the instance binding wins.
  • One static, one dynamic → the dynamic value wins.
  • Both dynamic → the component’s host binding wins.

The consequence to design around: a component that dynamically binds a host property has effectively claimed it, and consumers cannot override it dynamically. If a value should be consumer-controllable, take it as an input() and bind that input on the host, rather than computing it internally.

A clean way to make a component’s styling configurable is to set custom properties on the host:

@Component({
host: { '[style.--card-accent]': 'accent()' },
styles: `:host { border-left: 4px solid var(--card-accent, #ccc); }`,
})
export class CustomCard {
readonly accent = input('#0066cc');
}

This is better than exposing class names or ::ng-deep: the component keeps ownership of its structure and exposes a small, named, documented styling API. The var(--card-accent, #ccc) fallback means it works when the consumer sets nothing.

Host bindings are how attribute directives do most of their work:

@Directive({
selector: '[highlightOnHover]',
host: {
'[class.highlighted]': 'hovered()',
'(mouseenter)': 'hovered.set(true)',
'(mouseleave)': 'hovered.set(false)',
},
})
export class HighlightOnHover {
protected readonly hovered = signal(false);
}
<article highlightOnHover>…</article>

The directive adds behaviour to an element it does not own and never touches the DOM directly.

export class CustomSlider {
@HostBinding('attr.aria-valuenow') value = 0;
@HostBinding('tabIndex')
get tabIndex(): number {
return this.disabled ? -1 : 0;
}
@HostListener('keydown', ['$event'])
onKeydown(event: KeyboardEvent): void { /* ... */ }
}

Angular’s guidance is unusually direct: always prefer the host property. These decorators exist exclusively for backwards compatibility.

The practical reasons, beyond the official position: host puts every host binding in one place next to the selector, where a reader can see the element’s full contract at a glance, rather than scattered across the class as decorators on unrelated members. And a @HostBinding on a getter re-evaluates on every check, which quietly makes it a template method call with the same cost.

The host element is usually the one that needs the semantics, and this is where most of a custom component’s accessibility lives:

@Component({
selector: 'custom-checkbox',
host: {
'role': 'checkbox',
'[attr.aria-checked]': 'checked()',
'[attr.aria-disabled]': 'disabled() ? "true" : null',
'[attr.tabindex]': 'disabled() ? -1 : 0',
'(click)': 'toggle()',
'(keydown.space)': 'toggle(); $event.preventDefault()',
},
})
export class CustomCheckbox { /* ... */ }

Points that generalise:

  • A custom interactive element needs an explicit role. A <div> with a click handler is invisible to assistive technology.
  • It needs to be focusable: tabindex="0" when enabled, -1 when disabled.
  • It needs keyboard handling. Native buttons respond to Space and Enter; a custom control must implement that itself.
  • State goes in ARIA attributes, not only in CSS classes. aria-checked, aria-expanded, aria-selected.
  • preventDefault() on Space, or the page scrolls under the user.

Before building any of this, consider whether a native element would do. <button> gives you focus, keyboard handling, semantics and platform conventions for free, and no amount of ARIA fully replicates it. Angular’s @angular/aria package also provides accessibility primitives worth checking before hand-rolling.

Mistake Consequence Fix
[role] as a property binding role is not aria--prefixed, so it is not converted Static 'role', or [attr.role]; data-* also needs attr.
Dynamic host binding on a consumer-configurable value Consumers cannot override it Take an input() and bind that
@HostListener on window/document in hand-written code Listener leaks if removal is forgotten Use host with a global target; Angular cleans up
Expensive getter under @HostBinding Re-evaluated on every check Use a computed and the host property
Manipulating the host through ElementRef.nativeElement Breaks SSR and hydration; bypasses sanitization Use host bindings
Interactive host without role, tabindex or key handlers Unusable without a mouse Add all three, or use a native element
ARIA state left implicit in a CSS class Assistive technology sees nothing Bind aria-* attributes
No preventDefault() on Space The page scrolls when activating Prevent the default
::ng-deep to let consumers restyle internals Deprecated; couples to internal structure Expose CSS custom properties