JavaScript frameworks like Angular provide great abstractions and useful APIs on top of the native Document Object Model (DOM) that can make your codebase more readable, maintainable, and efficient. But what do you do when you need to directly access an HTML element on the DOM in a manner that is type-safe?
Angular's template reference variables provide a useful API through which you can interact with DOM elements and child components directly in your Angular code. In the sections that follow, you will learn what template reference variables are and how you can use them in your Angular components and services to gain low-level, manual control over the template elements that you are referencing.
To get started using template reference variables, simply create a new Angular component or visit an existing one. To create a template reference variable, locate the HTML element that you want to reference and then tag it like so: #myVarName
. In the code below, a template reference variable is created that references the <div>
with id test-div
.
1 <div id="test-div" #myTestDiv>
2 </div>
Having successfully created a reference to an HTML element within the template, you can now access this element inside of the relevant Angular component TypeScript file.
Within your Angular component, use the ViewChild
decorator that Angular provides in order to bind to the previously created template reference variable. For HTML elements, use the ViewChild
decorator to create a new ElementRef
as shown below:
1 @ViewChild('myTestDiv') myTestDiv: ElementRef;
This ElementRef
gives your component direct access to the underlying HTML element when you use its nativeElement
field like this:
1 const divEl: HTMLDivElement = this.myTestDiv.nativeElement;
Warning: Template reference variables will remain null/undefined until the view portion of the component has finished initiating. Make sure that you only attempt to use these variables within the ngAfterViewInit
lifecycle hook or after this hook completes!
For more information on the ElementRef
type, check out the Angular documentation.
Accessing underlying HTML elements in your Angular templates is great, but what if you want to access child components within your template? This is also easy using template reference variables.
Using the same syntax above, you can create a template reference variable on a child component like this:
1 <app-test-component #myTestComp></app-test-component>
With your child component referenced, you can gain access to it in your Angular component class like this:
1 @ViewChild('myTestComp') myTestComp: TestComponent;
With your child component successfully captured, you can access it like this:
1 ngAfterViewInit(): void {
2 // We can access the TestComponent now that this portion of the view tree has been initiated.
3 this.myTestComp.saveTheWorld();
4 }
In this guide, you learned what template reference variables are in the Angular framework and how you can use them to gain typed references to both HTML elements located on the DOM and child components.
You should now be confident in your ability to use template reference variables while avoiding variable-naming conflicts. Mastery of template reference variables will allow you to create a type-safe solution to that 5-10% of cases where the Angular framework's direct DOM element bindings are not enough and a more manual solution is needed.
Explore these Angular courses from Pluralsight to continue learning: