Snippet

Custom Structural Directives with Typed Template Guards

A custom structural directive is only as safe as its template context typing. `ngTemplateContextGuard` is a static type-guard method the Angular compiler calls at compile time (via the Ivy template type-checker) to verify that variables declared with `let-foo` inside the directive's template actually match the context shape emitted from `createEmbeddedView`. Without it, `<ng-template let-x>` compiles even if `x` doesn't exist on the context object, and the mismatch only surfaces at runtime. Pairing this with `ngTemplateGuard_ifRole: 'binding'` also tells the compiler to narrow the type of the bound expression itself, so the template body sees `role` as `string`, not `string | null`.

snippet.js

javascript

import { Directive, Input, TemplateRef, ViewContainerRef } from '@angular/core';
 
interface IfRoleContext {
  $implicit: boolean;
  ifRole: string;
}
 
@Directive({
  selector: '[ifRole]',
  standalone: true,
})
export class IfRoleDirective {
  private hasView = false;
 
  constructor(
    private templateRef: TemplateRef<IfRoleContext>,
    private viewContainer: ViewContainerRef,
  ) {}
 
  @Input() set ifRole(role: string) {
    const allowed = role === 'admin';
    if (allowed && !this.hasView) {
      this.viewContainer.createEmbeddedView(this.templateRef, {
        $implicit: true,
        ifRole: role,
      });
      this.hasView = true;
    } else if (!allowed && this.hasView) {
      this.viewContainer.clear();
      this.hasView = false;
    }
  }
 
  static ngTemplateGuard_ifRole: 'binding';
 
  static ngTemplateContextGuard(
    dir: IfRoleDirective,
    ctx: unknown,
  ): ctx is IfRoleContext {
    return true;
  }
}

angular

Breakdown

interface IfRoleContext { $implicit: boolean; ifRole: string; }

Defines the exact shape exposed to `let-` variables inside the template — `$implicit` is what `let-x` binds to without a name.

static ngTemplateGuard_ifRole: 'binding';

Instructs the compiler to type-check and narrow the bound `ifRole` expression itself, not just the template context.

static ngTemplateContextGuard(dir: IfRoleDirective, ctx: unknown): ctx is IfRoleContext

A compile-time-only type predicate; the compiler calls this signature during type-checking, it never runs in the browser.

this.viewContainer.createEmbeddedView(this.templateRef, { $implicit: true, ifRole: role })

The actual runtime context object — its shape must match `IfRoleContext` exactly or the guard becomes a lie the compiler trusts.

Previous snippet Next snippet

More Expert JavaScript exercises →

Custom Structural Directives with Typed Template Guards

Related