Custom structural directives in Angular - Deep Dive

Overview - Custom structural directives

What is it?

Custom structural directives in Angular let you create your own special instructions that change the structure of the web page. They can add, remove, or rearrange parts of the page based on your rules. This helps you build reusable and dynamic layouts easily. Unlike regular directives that change appearance or behavior, structural directives change the actual HTML elements shown.

Why it matters

Without custom structural directives, developers would have to repeat complex HTML and logic everywhere or write bulky code inside components. This makes apps harder to maintain and less flexible. Custom structural directives let you package layout logic once and reuse it, saving time and reducing errors. They make your app cleaner and easier to update.

Where it fits

Before learning custom structural directives, you should understand Angular components, templates, and built-in structural directives like *ngIf and *ngFor. After mastering them, you can explore advanced Angular topics like dynamic component loading and reactive programming to build even more powerful apps.

Mental Model

Core Idea

A custom structural directive is a reusable instruction that changes which parts of the page exist or not, based on your own rules.

Think of it like...

It's like a stage director who decides which actors appear on stage and when, changing the play's scene dynamically based on the story.

Template HTML
  │
  ▼
[Custom Structural Directive]
  │
  ├─ Adds elements
  ├─ Removes elements
  └─ Rearranges elements
  │
  ▼
Rendered Page Structure

Build-Up - 7 Steps

1

Foundation

What structural directives do

Concept: Structural directives change the HTML structure by adding or removing elements.

Angular has built-in structural directives like *ngIf and *ngFor that show or hide elements or repeat them. They work by changing the DOM, not just styles or attributes.

Result

You see parts of the page appear or disappear based on conditions or lists.

Understanding that structural directives control the presence of elements is key to grasping how Angular builds dynamic pages.

2

Foundation

How to recognize structural directives

Concept: Structural directives use a star (*) prefix in templates to mark them as instructions that change structure.

For example, *ngIf="condition" means Angular will add or remove that element depending on the condition. The star is shorthand for a longer syntax that involves templates.

Result

You can identify structural directives easily by the * symbol in HTML templates.

Knowing the star syntax helps you spot and write structural directives correctly.

3

Intermediate

Creating a basic custom structural directive

🤔Before reading on: do you think a custom structural directive needs to manipulate the DOM directly or use Angular's template system? Commit to your answer.

Concept: Custom structural directives use Angular's TemplateRef and ViewContainerRef to add or remove template parts safely.

You create a directive class with @Directive decorator and inject TemplateRef (the template to render) and ViewContainerRef (where to insert it). Then you control when to create or clear views.

Result

You get a directive that can show or hide content based on your own logic.

Understanding TemplateRef and ViewContainerRef is essential because they let you control the page structure without touching the DOM directly.

4

Intermediate

Using input properties to control behavior

🤔Before reading on: do you think input properties on structural directives behave like normal inputs or need special handling? Commit to your answer.

Concept: Structural directives can accept inputs to decide when and how to change the structure, but inputs must be handled carefully to trigger view updates.

You define an @Input() property with the same name as the directive selector. When the input changes, you add or remove views accordingly. This lets you create flexible directives like *myIf="condition".

Result

Your directive reacts dynamically to input changes and updates the page structure.

Knowing how to bind inputs to structural directives unlocks powerful customization and reuse.

5

Intermediate

Understanding the microsyntax behind * prefix

🤔Before reading on: do you think the * syntax is just a shortcut or does it transform the template into something else? Commit to your answer.

Concept: The * prefix is syntactic sugar that Angular converts into an element with the directive applied.

For example,

becomes

. This means your directive works with templates, not direct elements.

Result

You realize that structural directives always work with templates, which explains why TemplateRef is injected.

Understanding microsyntax clarifies why structural directives behave differently from attribute directives.

6

Advanced

Handling multiple views and context data

🤔Before reading on: do you think structural directives can pass data to their templates? Commit to your answer.

Concept: Structural directives can create multiple views and pass context data to templates for dynamic rendering.

You use ViewContainerRef.createEmbeddedView(templateRef, context) to create views with data. The context object provides variables accessible inside the template using let- syntax.

Result

Your directive can render repeated or conditional content with custom data, like a simplified *ngFor.

Knowing how to pass context data lets you build powerful, reusable structural directives that adapt to different scenarios.

7

Expert

Optimizing and avoiding common pitfalls

🤔Before reading on: do you think creating and destroying views frequently affects performance? Commit to your answer.

Concept: Efficient structural directives minimize unnecessary view creation and destruction to improve performance and avoid bugs.

You can track state inside the directive and only update views when inputs change meaningfully. Also, be careful with nested directives and lifecycle hooks to prevent memory leaks.

Result

Your directive performs well in large apps and avoids common Angular pitfalls.

Understanding Angular's change detection and view lifecycle helps you write robust, efficient structural directives.

Under the Hood

Angular compiles templates into instructions that create or remove embedded views in the DOM. Structural directives receive a TemplateRef representing the template chunk and a ViewContainerRef representing where to insert it. When the directive decides to show content, it calls createEmbeddedView on the container, which clones the template and inserts it. When hiding, it clears the container. The * syntax transforms the element into an ng-template behind the scenes, so the directive always works with templates, not direct elements.

Why designed this way?

This design separates structure control from direct DOM manipulation, allowing Angular to manage rendering efficiently and safely. Using TemplateRef and ViewContainerRef abstracts the DOM, enabling Angular's change detection and rendering optimizations. The * syntax was introduced to make structural directives easy to write and read, hiding the complexity of ng-template syntax from developers.

Component Template
  │
  ▼
*myDirective="condition"
  │
  ▼ (transformed to)
<ng-template [myDirective]="condition">
  <element></element>
</ng-template>
  │
  ▼
Directive Class
  ├─ TemplateRef (template chunk)
  └─ ViewContainerRef (insertion point)
  │
  ▼
createEmbeddedView() / clear()
  │
  ▼
DOM updated dynamically

Myth Busters - 4 Common Misconceptions

Quick: Do you think structural directives directly manipulate the DOM elements they decorate? Commit to yes or no.

Common Belief: Structural directives directly change the DOM elements they are attached to.

Reality: Structural directives work with templates and create or remove embedded views; they do not manipulate the original element directly.

Why it matters: Believing this leads to confusion about how to write directives and why the * syntax is needed, causing errors in directive implementation.

Quick: Do you think the * prefix is optional for structural directives? Commit to yes or no.

Common Belief: You can write structural directives without the * prefix and they will work the same.

Reality: The * prefix is required because it tells Angular to transform the element into an ng-template; without it, the directive behaves like a normal attribute directive.

Why it matters: Omitting the * causes the directive not to work as intended, leading to bugs and confusion.

Quick: Do you think structural directives can only show or hide content? Commit to yes or no.

Common Belief: Structural directives only toggle visibility of elements.

Reality: Structural directives can add, remove, or rearrange any part of the template, including creating multiple views with different data.

Why it matters: Limiting your understanding restricts your ability to create powerful reusable directives that manipulate structure flexibly.

Quick: Do you think creating many embedded views in a structural directive has no performance impact? Commit to yes or no.

Common Belief: Creating and destroying embedded views frequently is cheap and has no noticeable effect.

Reality: Frequent view creation and destruction can hurt performance and cause memory leaks if not managed carefully.

Why it matters: Ignoring this leads to slow apps and hard-to-find bugs in large or complex Angular applications.

Expert Zone

1

Structural directives can leverage Angular's change detection by passing context objects, enabling fine-grained control over template variables.

2

The * syntax desugaring to ng-template allows structural directives to be combined and nested, but this can cause subtle bugs if not carefully managed.

3

Advanced structural directives can implement embedded view caching to improve performance by reusing views instead of destroying and recreating them.

When NOT to use

Avoid custom structural directives when simple attribute directives or component inputs can achieve the goal more clearly. For complex UI changes, consider using dynamic components or Angular's CDK portals instead. Also, if performance is critical and many views are created/destroyed rapidly, explore manual DOM manipulation with Renderer2 or third-party libraries.

Production Patterns

In real apps, custom structural directives are used to implement features like role-based content display, lazy loading placeholders, or custom looping with advanced filtering. They often encapsulate complex conditional rendering logic, making templates cleaner and easier to maintain. Experts also combine them with Angular's reactive forms and observables for dynamic UI updates.

Connections

React Hooks

Both manage UI behavior dynamically but React Hooks control state and effects inside components, while Angular structural directives control DOM structure externally.

Understanding structural directives helps appreciate how Angular separates structure control from component logic, unlike React's integrated approach.

Design Patterns - Decorator Pattern

Structural directives decorate templates by adding or removing parts, similar to how the decorator pattern adds behavior to objects dynamically.

Recognizing this pattern clarifies how directives extend template behavior without changing the original component code.

Theatre Stage Direction

Like a stage director controls which actors appear and when, structural directives control which parts of the UI appear and when.

This connection highlights the dynamic and conditional nature of UI rendering controlled by directives.

Common Pitfalls

#1 Trying to manipulate DOM elements directly inside a structural directive.

Wrong approach:

constructor(private el: ElementRef) { this.el.nativeElement.style.display = 'none'; }

Correct approach:

constructor(private templateRef: TemplateRef, private vcr: ViewContainerRef) {}

updateView(condition: boolean) {
if (condition) {
this.vcr.createEmbeddedView(this.templateRef);
} else {
this.vcr.clear();
}
}

Root cause:

Misunderstanding that structural directives work with templates and views, not direct DOM elements.

#2 Omitting the * prefix when using a structural directive in a template.

Wrong approach:

Content

Correct approach:

Content

Root cause:

Not knowing that the * syntax triggers Angular's microsyntax transformation needed for structural directives.

#3 Not clearing the ViewContainerRef before creating a new embedded view, causing duplicate content.

Wrong approach:

this.vcr.createEmbeddedView(this.templateRef); // called multiple times without clearing

Correct approach:

this.vcr.clear();
this.vcr.createEmbeddedView(this.templateRef);

Root cause:

Forgetting that ViewContainerRef accumulates views unless cleared, leading to repeated elements.

Key Takeaways

Custom structural directives let you control which parts of the page exist by adding or removing template chunks dynamically.

They work by using TemplateRef and ViewContainerRef to create or clear embedded views, not by manipulating DOM elements directly.

The * prefix in templates is essential syntax that tells Angular to transform the element into an ng-template for the directive to work.

Passing context data to embedded views allows structural directives to render dynamic content with variables inside templates.

Efficient structural directives manage view creation carefully to avoid performance issues and bugs in large applications.