Template variables help you use data from one part of a template in another part of the template. Use template variables to perform tasks such as respond to user input or finely tune your application's forms.
A template variable can refer to the following:
See the live example for a working example containing the code snippets in this guide.
In the template, you use the hash symbol, #
, to declare a template variable. The following template variable, #phone
, declares a phone
variable with the <input>
element as its value.
<input #phone placeholder="phone number" />
Refer to a template variable anywhere in the component's template. Here, a <button>
further down the template refers to the phone
variable.
<input #phone placeholder="phone number" /> <!-- lots of other elements --> <!-- phone refers to the input element; pass its `value` to an event handler --> <button type="button" (click)="callPhone(phone.value)">Call</button>
Angular assigns a template variable a value based on where you declare the variable:
<ng-template>
element, the variable refers to a TemplateRef
instance which represents the template. For more information on <ng-template>
, see How Angular uses the asterisk, *
, syntax in Structural directives.#var="ngModel"
, the variable refers to the directive or component on the element with a matching exportAs
name. NgForm
with template variablesIn most cases, Angular sets the template variable's value to the element on which it occurs. In the previous example, phone
refers to the phone number <input>
. The button's click handler passes the <input>
value to the component's callPhone()
method.
The NgForm
directive demonstrates getting a reference to a different value by referencing a directive's exportAs
name. In the following example, the template variable, itemForm
, appears three times separated by HTML.
<form #itemForm="ngForm" (ngSubmit)="onSubmit(itemForm)"> <label for="name">Name</label> <input type="text" id="name" class="form-control" name="name" ngModel required /> <button type="submit">Submit</button> </form> <div [hidden]="!itemForm.form.valid"> <p>{{ submitMessage }}</p> </div>
Without the ngForm
attribute value, the reference value of itemForm
would be the HTMLFormElement, <form>
. If an element is an Angular Component, a reference with no attribute value will automatically reference the component instance. Otherwise, a reference with no value will reference the DOM element, even if the element has one or more directives applied to it.
Just like variables in JavaScript or TypeScript code, template variables are scoped to the template that declares them.
Similarly, Structural directives such as *ngIf
and *ngFor
, or <ng-template>
declarations create a new nested template scope, much like JavaScript's control flow statements like if
and for
create new lexical scopes. You cannot access template variables within one of these structural directives from outside of its boundaries.
Define a variable only once in the template so the runtime value remains predictable.
An inner template can access template variables that the outer template defines.
In the following example, changing the text in the <input>
changes the value in the <span>
because Angular immediately updates changes through the template variable, ref1
.
<input #ref1 type="text" [(ngModel)]="firstExample" /> <span *ngIf="true">Value: {{ ref1.value }}</span>
In this case, the *ngIf
on <span>
creates a new template scope, which includes the ref1
variable from its parent scope.
However, accessing a template variable from a child scope in the parent template doesn't work:
<input *ngIf="true" #ref2 type="text" [(ngModel)]="secondExample" /> <span>Value: {{ ref2?.value }}</span> <!-- doesn't work -->
Here, ref2
is declared in the child scope created by *ngIf
, and is not accessible from the parent template.
A template input variable is a variable with a value that is set when an instance of that template is created. See: Writing structural directives
Template input variables can be seen in action in the long-form usage of NgFor
:
<ul> <ng-template ngFor let-hero [ngForOf]="heroes"> <li>{{hero.name}} </ng-template> </ul>
The NgFor
directive will instantiate this heroes
array, and will set the hero
variable for each instance accordingly.
When an <ng-template>
is instantiated, multiple named values can be passed which can be bound to different template input variables. The right-hand side of the let-
declaration of an input variable can specify which value should be used for that variable.
NgFor
for example also provides access to the index
of each hero in the array:
<ul> <ng-template ngFor let-hero let-i="index" [ngForOf]="heroes"> <li>Hero number {{i}}: {{hero.name}} </ng-template> </ul>
© 2010–2023 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://angular.io/guide/template-reference-variables