Angular

Getting Started with Custom Structural Directives in Angular

Published Nov 22, 2021

Updated Feb 13, 2023

5 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Introduction

Angular comes with many built-in directives. Some of them (eg. NgIf, NgModel or FormControlDirective) are used daily by Angular developers. Those directives can be split into 2 categories:

Attribute directives

They can be used to modify the appearance of behavior of Angular components and DOM elements. For example:
Structural directives

They can be used to manipulate the HTML structure in the DOM. Using them, we can change the structure of part of the DOM that they control. For example:
- NgIf
- NgForOf
- NgSwitch

In this article, I will focus on the latter.

Creating a custom structural directive

As I've mentioned above, there are a couple of built-in structural directives in Angular. However, we might come across a case that the ones provided with the framework don't solve. This is where a custom structural directive might help us resolve the issue. But how do we write one?

All the code examples in this article use the Angular CLI or Nx CLI generated project as a starting point. You can generate a project using the following command, or use Stackblitz starter project.

npx create-nx-workspace --preset=angular --prefix=csd --appName=custom-structural-directive

# or
# ng new custom-structural-directive --prefix=csd

NgIf directive clone

Let's learn the basic concepts by reimplementing the basic features of the NgIf directive. We will call it CsdIf (CSR prefix stands for Custom Structural Directive :))

The structural directive is actually just a regular directive (with some additional syntactic sugars provided by Angular). So we can start with creating a module and empty directive using AngularCLI:

ng generate module if
ng generate directive if/if --module if

# or shorthand
# ng g m if
# ng g d if/if --module if

our new directive should look like this:

import { Directive } from '@angular/core';

@Directive({
  selector: '[csdIf]',
})
export class IfDirective {
  constructor() {}
}

Let's implement the basic functionality of displaying the content if passed value is true.

<h2 *csdIf="true">My visible conditional header</h2>
<h2 *csdIf="false">My hidden conditional header</h2>

To achieve that, we need a couple of elements:

an input that will determine whether to show or hide the content (@Input)
a reference to the template that we want to conditionally display (TemplateRef)
a container that will provide us with access to Angular's view (ViewContainerRef)

The input can be just a regular class property with Angular's @Input decorator. The important thing is to use a proper naming convention. For it to work as it does in the example code shown above, we need to name the property the same as the attribute's selector:

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

@Directive({
  selector: '[csdIf]',
})
export class IfDirective {
  @Input() csdIf: boolean = false;

  constructor() {}
}

Now our directive has the information whether to display the content or not but we need to also gain access to the TemplateRef and ViewContainerRef instances. We can do that by injecting them via a constructor:

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

@Directive({
  selector: '[csdIf]',
})
export class IfDirective {
  @Input() csdIf: boolean = false;

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

Now we have all the necessary tools and information to display or hide the content. We can use ViewContainerRef's createEmbeddedView method to display and clear method to remove the content. Important note: To make sure the csdIf property is assigned already, we need to use ngOnInit lifecycle hook.

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

@Directive({
  selector: '[csdIf]',
})
export class IfDirective implements OnInit {
  @Input() csdIf: boolean = false;

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

  ngOnInit(): void {
    if (this.csdIf) {
      this.vcr.createEmbeddedView(this.templateRef);
    } else {
      this.vcr.clear();
    }
  }
}

With this implementation, the following example already works as expected.

<h2 *csdIf="true">My visible conditional header</h2>
<h2 *csdIf="false">My hidden conditional header</h2>

There is still a problem with this implementation. Let's try to use the following example:

<input id="showInput" type="checkbox" [(ngModel)]="showInput" />
<label for="showInput">Show conditional header</label>
<h2 *csdIf="showInput">My conditional header</h2>

The "My conditional header" is displayed correctly when the page renders but as soon as we uncheck the showInput, our header doesn't disappear as we would expect. This is because we only check the csdIf input value inside of ngOnInit, but we do not react to the input's changes. To resolve this, we can either use ngOnChanges lifecycle hook or modify the csdIf to be a setter rather than just a property. I will show you the later solution but implementing it using ngOnChanges should be very similar.

As a first step, let's modify the csdIf to be a setter, and store its value in a private property show.

@Directive({
  selector: '[csdIf]',
})
export class IfDirective implements OnInit {
  private show = false;
  @Input() set csdIf(show: boolean) {
    this.show = show;
  }

  /* constructor */

  ngOnInit(): void {
    if (this.show) {
      this.vcr.createEmbeddedView(this.templateRef);
    } else {
      this.vcr.clear();
    }
  }
}

Secondly, when the new csdIf value is set, we need to perform the same logic as we do in ngOnInit. We need to make sure though that we don't render the template twice so we can clear the view first in all cases.

@Directive({
  selector: '[csdIf]',
})
export class IfDirective implements OnInit {
  private show = false;
  @Input() set csdIf(show: boolean) {
    this.show = show;
    this.vcr.clear();
    if (this.show) {
      this.vcr.createEmbeddedView(this.templateRef);
    }
  }

  /* constructor */

  ngOnInit(): void {
    this.vcr.clear();
    if (this.show) {
      this.vcr.createEmbeddedView(this.templateRef);
    }
  }
}

As a final step, let's refactor to remove the code duplication by extracting the common logic into a method.

@Directive({
  selector: '[csdIf]',
})
export class IfDirective implements OnInit {
  private show = false;
  @Input() set csdIf(show: boolean) {
    this.show = show;
    this.displayTemplate();
  }

  /* constructor */

  ngOnInit(): void {
    this.displayTemplate();
  }

  private displayTemplate() {
    this.vcr.clear();
    if (this.show) {
      this.vcr.createEmbeddedView(this.templateRef);
    }
  }
}

Now, our second example works as expected:

<input id="showInput" type="checkbox" [(ngModel)]="showInput" />
<label for="showInput">Show conditional header</label>
<h2 *csdIf="showInput">My conditional header</h2>

Handling additional parameters - else template

The CsdIf directive shows and hides the content based on the boolean input correctly. But the original NgIf directive allows for specifying an alternative template via the "else" property as well. How do we achieve this behavior in our custom directive? This is where understanding the "syntactic sugar" that stands behind the structural directives is crucial. The following NgIf syntax:

<h2 *ngIf="show; else alternativeTemplate">My conditional header</h2>
<ng-template #alternativeTemplate>
  <h2>My alternative header</h2>
</ng-template>

is actually equivalent to the following syntax:

<ng-template [ngIf]="show" [ngIfElse]="alternativeTemplate">
  <h2>My conditional header</h2>
</ng-template>
<ng-template #alternativeTemplate>
  <h2>My alternative header</h2>
</ng-template>

This means that the else property is actually becoming ngIfElse input parameter. In general, we can construct the property name by concatenating the attribute following * and the capitalized property name (eg. "ngIf" + "Else" = "ngIfElse""). In case of our custom directive it will become "csdIf" + "Else" = "csdIfElse

<h2 *csdIf="show; else alternativeTemplate">My conditional header</h2>
<ng-template #alternativeTemplate>
  <h2>My alternative header</h2>
</ng-template>

is equivalent to

<ng-template [csdIf]="show" [csdIfElse]="alternativeTemplate">
  <h2>My conditional header</h2>
</ng-template>
<ng-template #alternativeTemplate>
  <h2>My alternative header</h2>
</ng-template>

By analyzing the "unwrapped" syntax we can notice the the reference to an alternative template is passed via the csdIfElse property. Let's add and handle that property in the custom directive implementation:

@Directive({
  selector: '[csdIf]',
})
export class IfDirective implements OnInit {
  private show = false;

  @Input() set csdIf(show: boolean) {
    this.show = show;
    this.displayTemplate();
  }

  @Input() csdIfElse?: TemplateRef<unknown>;

  /* constructor */

  ngOnInit(): void {
    this.displayTemplate();
  }

  private displayTemplate() {
    this.vcr.clear();
    if (this.show) {
      this.vcr.createEmbeddedView(this.templateRef);
    } else if (this.csdIfElse) {
      this.vcr.createEmbeddedView(this.csdIfElse);
    }
  }
}

This addition makes our directive much more useful, and allows for displaying content for cases when the condition is true or false.

If something is not clear, or you want to play with the example directive please visit the example on Stackblitz.

Real life example

The above example is very simple, but it gives you tools to create your own custom directive when you need it. If you want to have a look at some real-life custom directive example that we've found useful at This Dot Labs, I suggest checking out our route-config open source library. You can read more about it in one of our articles:

Summary

In this article, we've learnt how to write a simple custom structural directive that handles additional inputs. We've covered the syntactic sugar that stands behind the structural directive, and how it translates into directive's inputs. In the second part, I will show you how to add some additional functionalities to the custom structural directive and present ways to improve type checking experience for the custom directive's templates.

In case you have any questions, you can always tweet or DM me at @ktrz. I'm always happy to help!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Chris Trześniewski
Software Engineer, ultra-marathoner. He is passionate about functional programming in JavaScript and loves working with RxJS. In his free time he likes to go jogging.
@ktrz__@ktrz

"Do What Matters with Who Matters While It Matters" Mark Techson on Leadership

Tracy Lee and Rob Ocel sit down with Mark Thompson, aka "Mark Techson", to explore key themes around personal branding, workplace culture, and leadership. Mark shares his journey of building a strong personal brand, discussing how consistent online presence can shape public perception and create professional opportunities. The conversation provides valuable insights into the art of leading without a formal title, emphasizing the importance of cultural sensitivity and gradual influence in workplace environments. A significant portion of the discussion is devoted to Mark's motto of "Do what matters with who matters while it matters." This practical approach encourages listeners to focus on meaningful work, prioritize important relationships, and make the most of their time. Mark also reflects on the challenges of maintaining resilience in the face of personal adversity, offering a candid look at how to balance personal and professional life effectively. Listeners will find actionable advice on how to take control of their career trajectory, foster a positive work culture, and navigate the complexities of leadership, all while staying true to themselves. Chapters [00:00] Introduction [02:19] Personal Branding and Online Presence [06:36] Navigating Workplace Culture [08:56] The Story Behind 'Well Dressed Wednesdays' [11:12] Developing the "Do What Matters" Framework [13:29] Balancing Public and Private Life [18:10] Overcoming Personal Challenges [20:28] Taking Control of Your Career [22:49] Practical Takeaways for Listeners Follow Mark on Social Media Twitter Linkedin Github Bluesky Sponsored by Wix Studio....

Aug 20, 2024

2 mins

JavaScriptAngularEngineering Leadership

Advanced TypeScript - Schema Validation with Zod - Type Inference & Generics with Josh Goldberg

TypeScript has become an essential tool for developers seeking to enhance the robustness and maintainability of their codebases. While many are familiar with the basics of TypeScript, there are advanced concepts that can take your TypeScript skills to the next level. In this JSDrops Training by Josh Goldberg, viewers will explore some of these advanced TypeScript concepts, including schema validation using Zod, leveraging TypeScript's powerful type inference capabilities, and effectively utilizing TypeScript's type system. One crucial aspect of building reliable applications is ensuring data integrity. This is where schema validation libraries like Zod come into play. Zod allows developers to define complex data models and validate incoming data against these models. By leveraging Zod's expressive API, developers can easily define object schemas, conditional types, and literal types, ensuring that the data meets the expected structure and constraints. This not only helps catch errors early but also provides a clear and concise way to handle data validation and error handling. TypeScript's type inference is a powerful feature that can save developers time and effort. By allowing TypeScript to infer types based on context, developers can write cleaner and more concise code. Additionally, leveraging generics can further enhance type inference. Generics enable developers to write reusable code that adapts to different types, making logic inference more flexible and efficient. Understanding how to effectively use generics and type inference can greatly improve code readability and maintainability. While advanced TypeScript concepts can greatly enhance code quality, it is important to strike a balance between utilizing these features and maintaining code simplicity. It is crucial to understand TypeScript terminology and best practices to avoid overcomplicating code. Additionally, debugging techniques specific to TypeScript can help identify and resolve issues more efficiently. By carefully considering when and where to apply advanced TypeScript concepts, developers can create code that is both powerful and easy to understand....

Jul 26, 2024

2 mins

TypeScriptWeb Development

How to Write a Custom Structural Directive in Angular - Part 2

How to write a custom structural directive in Angular - part 2 In the previous article I've shown how you can implement a custom structural directive in Angular. We've covered a simple custom structural directive that implements interface similar to Angular's NgIf directive. If you don't know what structural directives are, or are interested in basic concepts behind writing custom one, please read the previous articlefirst. In this article, I will show how to create a more complex structural directive that: - passes properties into the rendered template - enables strict type checking for the template variables Starting point I am basing this article on the example implemented in the part 1 article. You can use example on Stackblitz as a starting point if you wish to follow along with the code examples. Custom NgForOf directive This time, I would like to use Angular's NgForOf directive as an example to re-implement as a custom CsdFor directive. Let's start off by using Angular CLI to create a new module, and directive files: ` First, we need to follow similar steps as with the CsdIf directive. - add constructor with TemplateRef, and ViewContainerRef injected - add an @Input property to hold the array of items that we want to display ` Then, in the ngOnInit hook we can render all the items using the provided template: ` Now, we can verify that it displays the items properly by adding the following template code to our AppComponent. ` It displays the items correctly, but doesn't allow for changing the displayed collection yet. To implement that, we can modify the csdForOf property to be a setter and rerender items then: ` Now, our custom directive will render the fresh items every time the collection changes (its reference). Accessing item property The above example works nice already, but it doesn't allow us to display the item's content yet. The following code will display "no content" for each template rendered. ` To resolve this, we need to provide a value of each item into a template that we are rendering. We can do this by providing second param to createEmbeddedView method of ViewContainerRef. ` The question is what key do we provide to assign it under item variable in the template. In our case, the item is a default param, and Angular uses a reserved $implicit key to pass that variable. With that knowledge, we can finish the renderItems method: ` Now, the content of the item is properly displayed: Adding more variables to the template's context Original NgForOf directives allows developers to access a set of useful properties on an item's template: - index - the index of the current item in the collection. - count - the length of collection - first - true when the item is the first item in the collection - last - true when the item is the last item in the collection - even - true when the item has an even index in the collection - odd - true when the item has an odd index in the collection We can pass those as well when creating a view for a given element along with the $implicit parameter: ` And now, we can use those properties in our template. ` Improve template type checking Lastly, as a developer using the directive it improves, the experience if I can have type checking in the template used by csdFor directive. This is very useful as it will make sure we don't mistype the property name as well as we only use the item, and additional properties properly. Angular's compiler allows us to define a static ngTemplateContextGuard methods on a directive that it will use to type-check the variables defined in the template. The method has a following shape: ` This makes sure that the properties of template rendered by our DirectiveClass will need to conform to DirectiveContext. In our case, this can be the following: ` Now, if we eg. try to access item's property that doesn't exist on the item's interface, we will get a compilation error: ` The same would happen if we made a typo in any of the context property names: ` Summary In this article, we've created a clone of Angular's built-in NgForOf directive. The same approach can be used to create any other custom directive that your project might need. As you can see, implementing a custom directive with additional template properties and great type checking experience is not very hard. If something was not clear, or you want to play with the example directive, please visit the example on Stackblitz. In case you have any questions, you can always tweet or DM me at @ktrz. I'm always happy to help!...

Dec 13, 2021

5 mins

AngularTypeScriptDirectiveWeb Development

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

In this episode of the Modern Web Podcast, Danny Thompson sits down with Ferdinand Como and Baptiste Leproux from Nuxt Labs to uncover the story behind Nuxt Studio, a tool that's transforming how developers and non-technical users interact with Nuxt applications. Ferdinand and Baptiste share how Nuxt Studio bridges the gap between developer customization and user-friendly content management. Built to empower agencies, freelancers, and their clients, Nuxt Studio combines powerful features like live previews, Vue component integration, and schema-driven forms to make managing content seamless. The conversation also explores the broader mission of Nuxt Labs—building sustainable open-source tools that enhance developer experience and meet real-world needs. With insights into the future of Nuxt Studio and its potential to scale for larger organizations, this episode is a must-listen for anyone passionate about innovation in web development. Chapters 1. Introduction and Setting the Stage (00:00:00) 2. The Vision Behind Nuxt Studio (00:03:10) 3. Nuxt Studio’s Core Features (00:08:45) 4. Challenges in Building Nuxt Studio (00:16:20) 5. Target Audience and Use Cases (00:22:35) 6. Sustainability in Open Source (00:29:00) 7. The Future of Nuxt Studio (00:35:10) 8. Nuxt Studio’s Role in the Nuxt Ecosystem (00:42:30) 9. Closing Thoughts and What’s Next (00:48:00) 10. Sponsor Shoutout and Wrap-Up (00:53:20) Follow Baptiste Leproux and Ferdinand Coumau Baptiste Twitter: https://x.com/_larbish Ferdinand Twitter: https://x.com/CoumauFerdinand Baptiste Linkedin: https://www.linkedin.com/in/baptiste-leproux-618842b0/ Ferdinand Linkedin: https://www.linkedin.com/in/ferdinand-coumau-nuxt/ Sponsored by This Dot: thisdot.co...

Nov 20, 2024

2 mins

VueNuxtJS

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Getting Started with Custom Structural Directives in Angular

Introduction

Creating a custom structural directive

NgIf directive clone

Handling additional parameters - else template

Real life example

Summary

Chris Trześniewski

You might also like

"Do What Matters with Who Matters While It Matters" Mark Techson on Leadership

Advanced TypeScript - Schema Validation with Zod - Type Inference & Generics with Josh Goldberg

How to Write a Custom Structural Directive in Angular - Part 2

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Let's innovate together!

You might also like

"Do What Matters with Who Matters While It Matters" Mark Techson on Leadership

Advanced TypeScript - Schema Validation with Zod - Type Inference & Generics with Josh Goldberg

How to Write a Custom Structural Directive in Angular - Part 2

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau