Custom structural directives in Angular

Introduction

Custom structural directives let you change the layout by adding or removing parts of the page. They help you create reusable and dynamic HTML structures.

You want to show or hide elements based on complex conditions.

You need to repeat a block of HTML with custom logic.

You want to create your own version of *ngIf or *ngFor with special behavior.

You want to add or remove elements dynamically without changing the component code.

Syntax

Angular

import { Directive, TemplateRef, ViewContainerRef, Input } from '@angular/core';

@Directive({
  selector: '[appMyDirective]'
})
export class MyDirective {
  constructor(
    private templateRef: TemplateRef<any>,
    private viewContainer: ViewContainerRef
  ) {}

  @Input() set appMyDirective(condition: boolean) {
    if (condition) {
      this.viewContainer.createEmbeddedView(this.templateRef);
    } else {
      this.viewContainer.clear();
    }
  }
}

TemplateRef is the HTML block you want to control.

ViewContainerRef is where Angular inserts or removes that block.

Examples

This directive shows the element only if the condition is true, similar to *ngIf.

Angular

import { Directive, TemplateRef, ViewContainerRef, Input } from '@angular/core';

@Directive({ selector: '[appShowIf]' })
export class ShowIfDirective {
  constructor(private templateRef: TemplateRef<any>, private viewContainer: ViewContainerRef) {}

  @Input() set appShowIf(condition: boolean) {
    if (condition) {
      this.viewContainer.createEmbeddedView(this.templateRef);
    } else {
      this.viewContainer.clear();
    }
  }
}

This directive repeats the element a given number of times.

Angular

import { Directive, TemplateRef, ViewContainerRef, Input } from '@angular/core';

@Directive({ selector: '[appRepeat]' })
export class RepeatDirective {
  constructor(private templateRef: TemplateRef<any>, private viewContainer: ViewContainerRef) {}

  @Input() set appRepeat(times: number) {
    this.viewContainer.clear();
    for (let i = 0; i < times; i++) {
      this.viewContainer.createEmbeddedView(this.templateRef);
    }
  }
}

Sample Program

This example creates a custom directive appShowIf that works like *ngIf. Clicking the button toggles the message on and off.

Angular

import { Component, Directive, Input, TemplateRef, ViewContainerRef } from '@angular/core';

@Directive({ selector: '[appShowIf]' })
export class ShowIfDirective {
  constructor(private templateRef: TemplateRef<any>, private viewContainer: ViewContainerRef) {}

  @Input() set appShowIf(condition: boolean) {
    if (condition) {
      this.viewContainer.createEmbeddedView(this.templateRef);
    } else {
      this.viewContainer.clear();
    }
  }
}

@Component({
  selector: 'app-root',
  template: `
    <button (click)="toggle()">Toggle Message</button>
    <p *appShowIf="show">Hello! This message is controlled by a custom structural directive.</p>
  `
})
export class AppComponent {
  show = true;

  toggle() {
    this.show = !this.show;
  }
}

Important Notes

Always prefix your directive selectors to avoid conflicts.

Structural directives must use TemplateRef and ViewContainerRef to control DOM.

Use @Input() setter to react to changes in directive input.

Summary

Custom structural directives let you add or remove HTML blocks dynamically.

They use TemplateRef and ViewContainerRef to control the page layout.

You create them by writing a directive with an input property that controls when to show or hide content.