Angular Template Reference Variables: A #handle for Elements

Why it exists

Sometimes you need to perform simple interactions within a template without the overhead of creating component properties and event handlers. For example, reading a value from one element when another is clicked. Template reference variables provide a direct, lightweight way to achieve this entirely within the template's HTML.

The mental model

Think of a template reference variable as a temporary name tag you stick on an HTML element, component, or directive. This tag, created with a '#' prefix (like #phoneInput), lets other elements in the same template find and interact with the tagged element directly. It's like giving a person a nametag at a party so you can easily call them out from across the room without needing to know them beforehand.

How it works

You declare a variable by adding a hash-prefixed attribute to an element, such as <input #myInput>. Angular then makes myInput available throughout that template. By default, the variable references the DOM element itself. If you place it on an Angular component, it references the component instance, giving you access to its public methods and properties. You can then pass this variable to event handlers, like (click)="logValue(myInput.value)". The scope of this variable is strictly limited to the template where it is defined.

When to use it

Use it for simple, template-local interactions. A classic case is grabbing the value from an input field when a button is clicked, without needing a full ngModel two-way binding. It's also great for calling a public method on a child component from the parent's template, for example, (click)="childComponent.reset()".

When not to use it

Avoid using template reference variables when you need to access the element or component from your component's TypeScript class logic. They are designed for template-to-template communication. For accessing template elements from your class, the correct tool is the @ViewChild or @ViewChildren decorator. Also, don't confuse them with @let variables, which are for storing the result of an expression, not for referencing elements.

One canonical example

To get a user's name from an input field and display it in an alert without involving the component class, you can write: <input #nameInput placeholder="Enter your name"> <button (click)="alert(nameInput.value)">Greet</button> Here, #nameInput creates a reference to the input element. The button's click handler can then directly access its value property.