How to Use Template Reference Variables in Angular

Jul 12, 2020 • 4 Minute Read

Introduction

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.

Getting Started

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.

      <div id="test-div" #myTestDiv>
    </div>
    

Accessing Template Elements Using ViewChild

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:

      @ViewChild('myTestDiv') myTestDiv: ElementRef;

This ElementRef gives your component direct access to the underlying HTML element when you use its nativeElement field like this:

      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.

Using Template Reference Variables with Child Components

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:

      <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:

      @ViewChild('myTestComp') myTestComp: TestComponent;

With your child component successfully captured, you can access it like this:

      ngAfterViewInit(): void {
        // We can access the TestComponent now that this portion of the view tree has been initiated.
        this.myTestComp.saveTheWorld();
    }
    

Conclusion

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.

Learn More

Explore these Angular courses from Pluralsight to continue learning: