Template reference variables (#varName) create named references to DOM elements and component instances within a template — enabling the template to pass references to event handlers or access component APIs without going through the component class. @HostBinding and @HostListener (or their functional equivalents host metadata) let a directive or component bind to its own host element’s properties and events, making directives that manipulate the host element clean and encapsulated.
Template Reference Variables
@Component({
selector: 'app-post-search',
standalone: true,
imports: [FormsModule],
template: `
<!-- #searchInput creates a reference to the input DOM element ────────── -->
<input #searchInput
type="text"
[(ngModel)]="query"
placeholder="Search...">
<!-- Pass the reference directly in the template ─────────────────────── -->
<button (click)="onSearch(searchInput.value)">Search</button>
<button (click)="searchInput.focus()">Focus Input</button>
<p>Character count: {{ searchInput.value.length }}</p>
<!-- Reference to a child component instance ────────────────────────── -->
<app-post-list #postList />
<button (click)="postList.refresh()">Refresh List</button>
`,
})
export class PostSearchComponent {
query = '';
onSearch(value: string): void { console.log('Searching:', value); }
}
// ── @HostBinding and @HostListener — directive modifying its host ──────────
import { Directive, HostBinding, HostListener, Input, signal } from '@angular/core';
@Directive({
selector: '[appHighlight]', // applied as: <div appHighlight>
standalone: true,
})
export class HighlightDirective {
@Input('appHighlight') highlightColor = 'yellow'; // <div appHighlight="pink">
private isHovered = signal(false);
// ── @HostBinding — binds to a property of the host element ──────────────
@HostBinding('style.backgroundColor')
get backgroundColor(): string {
return this.isHovered() ? this.highlightColor : 'transparent';
}
@HostBinding('style.cursor') cursor = 'pointer';
@HostBinding('class.highlighted') isHighlighted = false;
// ── @HostListener — listens for events on the host element ──────────────
@HostListener('mouseenter')
onMouseEnter(): void {
this.isHovered.set(true);
this.isHighlighted = true;
}
@HostListener('mouseleave')
onMouseLeave(): void {
this.isHovered.set(false);
this.isHighlighted = false;
}
@HostListener('click', ['$event'])
onClick(event: MouseEvent): void {
console.log('Highlighted element clicked at:', event.clientX, event.clientY);
}
}
// ── Modern alternative: host metadata in @Component/@Directive ────────────
@Directive({
selector: '[appHighlight]',
standalone: true,
host: {
'(mouseenter)': 'onMouseEnter()',
'(mouseleave)': 'onMouseLeave()',
'[style.backgroundColor]': 'isHovered() ? highlightColor : "transparent"',
'[style.cursor]': '"pointer"',
},
})
export class HighlightDirectiveModern {
highlightColor = input('yellow', { alias: 'appHighlight' });
isHovered = signal(false);
onMouseEnter() { this.isHovered.set(true); }
onMouseLeave() { this.isHovered.set(false); }
}Note: Template reference variables (
#ref) on a plain HTML element reference the HTMLElement. On a component (<app-post-list #list />), the reference is the component class instance — you can call its public methods and access its public properties. On a directive (<input ngModel #model="ngModel" />), the reference is the directive instance when the exported name matches. This allows templates to read directive state (model.valid, model.dirty) for local UI logic without going through the component class.Tip: The
host metadata property in @Component or @Directive is the modern equivalent of @HostBinding and @HostListener. Using host: { '(click)': 'onClick()', '[class.active]': 'isActive' } in the decorator metadata is more concise, avoids extra method decorators, and makes it clear at a glance what the component does to its host element. The Angular team recommends host metadata over decorators for new code.Warning: Template reference variables are scoped to the template — you cannot access
#searchInput from the component class (that requires @ViewChild). Template references are for template-to-template communication: passing an element to an event handler or reading a property in interpolation within the same template. Do not confuse template references with @ViewChild — they serve different purposes and scope.Common Mistakes
Mistake 1 — Accessing a template reference variable from the component class (undefined)
❌ Wrong — declaring #myInput in template and trying to use this.myInput in the class; it is a template-only reference.
✅ Correct — use @ViewChild('myInput') myInput!: ElementRef in the class to access template DOM elements.
Mistake 2 — Using @HostListener for events that should be component events (wrong level)
❌ Wrong — @HostListener('click') inside a component when the template already has a click handler; fires twice.
✅ Correct — use @HostListener in directives that augment host elements; use template event bindings for component-owned elements.