What is the scope of the template reference variable in Angular?

Question

What is the scope of the template reference variable in Angular?

I can not find a clear answer to my question in documentation. Even though empirically I can say that the whole template can access the template reference variable.

1 Is it the case? Is the template reference variable guaranteed to be accessible in the whole template?

2 Or is the template reference variable accessible only in the child and sibling elements of the element which is referenced by the template reference variable?

Over here I found the following statement:

Use template variables to refer to elements — The newHero template variable refers to the <input> element. You can reference newHero from any sibling or child of the <input> element.

Does it mean that only the 2 is guaranteed by Angular?

Answer 1

Template reference variable could be accessed from anywhere in the template as long as the corresponding element is present in the DOM.

For eg. you cannot access a template ref variable inside an <ng-template> element if it is not yet rendered.

<ng-template #templateOne let-message let-showAdditional="show">
  <div #templateDiv>
    One <br />
  </div>
</ng-template>

<ng-container *ngIf="templateDiv">
  Got template div
</ng-container>

Here Angular will throw an error

Property 'templateDiv' does not exist on type 'SomeComponent'.

because the element that is referenced by the variable is not present in the DOM.

---

Regarding your point 2.

You can reference newHero from any sibling or child of the element.

They were referring to the specific tutorial. Notice it didn't say

You can reference newHero only from any sibling or child of the element.

Answer 2

As stated here:

You can refer to a template reference variable anywhere in the component's template.

Answer 3

It turns out, in newer versions of Angular (I'm using v18) you can't access template variables from the outside if they're inside an @if or a @for block. Indeed, this could be mentioned in the docs.

 <!-- won't work, you get 'Property `variable` does not exist on type SomeComponent'-->
{{variable.offsetHeight}}

@if (condition) {
<div #variable></div>
}

If you still want to use variables behind if or for statements, you should create a new viewChild variable in your TS file.

// with signals:
variable = viewChild<ElementRef<HTMLDivElement>>('variable');
// or with the older method:
@ViewChild('variable') variable: ElementRef<HTMLDivElement>;

And then in the HTML template:

{{variable().nativeElement?.scrollHeight  }}

Be sure to use ?. operator or something similar because variable().nativeElement might not exist if the element isn't rendered because of the if condition.