Host Binding and Host Listening
What the host element is
Section titled “What the host element is”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.
The host property
Section titled “The host property”@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.
attr. versus property
Section titled “attr. versus property”[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' }Binding collisions
Section titled “Binding collisions”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.
CSS custom properties
Section titled “CSS custom properties”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.
Directives and the host
Section titled “Directives and the host”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.
@HostBinding and @HostListener
Section titled “@HostBinding and @HostListener”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.
Accessibility
Section titled “Accessibility”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,-1when 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.
Common mistakes
Section titled “Common mistakes”| 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 |
Related pages
Section titled “Related pages”- Input Properties
- Content Queries and Content Projection
- Templates in Angular
- Angular Security
- Directives basics