Angular provides several built-in abstractions that allow for building a reliable system. The most elaborate among them is Directives. Unlike components (which are actually a specific type of directive), the mental model of attribute and structural directives is often more challenging to grasp at the initial stages of learning Angular. However, as experience grows, their role becomes clearer — they offer a powerful way to structure and decompose both application and system logic.
In this article, we will focus on examples of system-level code where directives play a key role in ensuring reusability, seamless integration with third-party APIs, and, most importantly, extending functionality without the need to modify the source code.
A brief introduction:
This article assumes you already have a basic understanding of directives, so we won’t be recapping the documentation, which covers the types of directives and how to define them. Instead, we’ll focus on key approaches and practical guidelines for their implementation.
🎯 One task, one directive
Just like any other structured unit, a directive should have a single, well-defined purpose. This becomes especially important when viewed through the lens of the Directive composition API, where logic is built from a system of directives, each responsible for a specific task.
Additionally, a directive should affect only the element to which it is applied. Keeping this boundary ensures predictable behavior and maintains a clear relationship between objects:
🧩 Extend, don’t modify
Directives allow us to extend the functionality of nodes by adding new behaviors to them. At the same time, we don’t modify the source code of the node itself, whether it’s a component or any other DOM element.
This approach can be compared to our face and glasses. Glasses can easily be taken off and put on without altering the structure of the face. Moreover, depending on the type of glasses, they can correct our vision or protect our eyes from the sun. This is similar to how directives can enhance the functionality of the target node to which they are attached.
Directives as part of a virtual node
Before we move on to real examples, let’s also consider some important technical details when working with directives.
🔗 Managing dependencies
When a directive is applied to a node, it becomes a part of the NodeInjector tree in the dependency injection system, enabling it to interact with various abstractions related to that node.
⚠️ It is important to note that the documentation refers to this concept as the ElementInjector hierarchy. While both terms describe the injection system tied to nodes, NodeInjector is the actual class name used in the Ivy engine’s source code.
For instance, we can get a reference to the directive’s element if it is attached to a DOM element:
// directive's .ts
private readonly elementRef = inject(ElementRef<HTMLElement>);
/* directive usage
<div [directive]></div>
*/
If a directive is applied to an <ng-template> (or used with the * shorthand) we can get a reference to the template itself:
// directive's .ts
private readonly templateRef = inject(TemplateRef);
/* directive usage
<ng-template [directive]></ng-template>
<div *directive></div>
*/
These are special objects that are automatically available through the NodeInjector. Additionally, a directive can coexist with other directives on the same node and register its own providers, allowing them to access its instance and dependencies.
📋 Let’s use the following code snippet as a basis, featuring a root component and a child element with applied directives:
<app-root>
<input appAutoFocus appTooltip="Tooltip" formControlName="name" />
</app-root>
Now, let’s imagine a hierarchy of nodes and their corresponding objects:
To enable references to objects associated with nodes, Angular utilizes several data structures alongside the DOM tree. The presence of these virtual trees also enables the use of directives and references to elements like <ng-template> and <ng-container>, which do not exist in the actual DOM.
Directives as behavioral aspects
In the previous sketch, you may have noticed that when we use the [formControlName] from ReactiveFormsModule, the corresponding NodeInjector has multiple directives, along with their respective providers:
💡 This highlights another key feature: the ability to apply multiple directives under a common selector. Additionally, we can narrow the selection of nodes by adding qualifying selectors to the primary one for specific directives. For instance, the FormControlName directive from our example is applied using [formControlName], whereas DefaultValueAccessor has a more specific selector input:not([type=checkbox])[formControlName].
All the aforementioned characteristics of directives exhibit certain traits of Aspect-Oriented Programming (hereinafter AOP). This paradigm separates cross-cutting concerns from core logic, referring to such secondary tasks as aspects, and their implementation as advice. In the case of directives, specific behaviors are extracted into separate classes and activated when an element matches the selector. This is somewhat similar to a pointcut, which defines all the places where an advice applies.
📋 Let’s return to an <input/> with an attached control directive and add two additional attributes: required and minlength
<input formControlName="name" required minlength="5" />
Along with familiar HTML5 input attributes that provide some standardized behavior, Angular extends the node with additional functionality through directives matched to these attributes.
Importing the ReactiveFormsModule to apply the control directive ensures proper binding of all other directives that match their selectors, as they are all exported from the same module:
The names of some directives clearly reflect their responsibilities. Validator directives register the appropriate validators for the control model, while NgControlStatus handles binding a specific set of classes to a control element based on its state.
A detailed breakdown of all the directives in the forms module and their purposes is a topic for a separate article. For now, you can explore them in more depth in the source code of the forms package.
✨ Integrating new aspects
Let’s imagine we’re working on a project where a third-party library’s directive is used to display a context menu:
<tr [ngxContextMenu]="template"> ... </tr>
During late-stage testing, we discovered that the directive doesn’t support displaying the menu on mobile devices, where, due to the absence of a right-click, a long press is typically used instead:
In such cases, we usually create an issue and report it to the library authors, waiting for the missing functionality to be implemented. If we have enough time and the library is open-source, we can fork the repository, review its contribution guidelines, analyze the directive’s source code, implement the required feature while following all project conventions, write corresponding tests, and submit a PR for review.
But what if we need to solve this problem as quickly as possible due to business requirements? One solution could be to introduce an additional behavioral aspect for the third-party library directive. Pseudocode:
import { fromLongPress } from './rxjs-utils';
@Directive({
selector: '[ngxContextMenu]'
})
export class LongPressContextMenu {
private readonly el = inject(ElementRef).nativeElement;
private readonly menu = inject(NgxContextMenu);
constructor() {
fromLongPress(this.el)
.pipe(takeUntilDestroyed())
.subscribe(event => this.menu.open(event));
}
}
I intentionally use the same selector [ngxContextMenu] for our custom directive since it complements missing logic rather than optional behavior. This approach lets us introduce the new aspect across the application by adjusting component imports at the .ts level without affecting .html:
One of the main benefits of this approach is the reversibility of changes. The additional behavior is introduced without modifying the core logic’s source code. If we need to introduce aspect functionality only under certain conditions, we can define a more specific selector for it. Moreover, if the aspect is later implemented by an external library, it can be safely removed.
✂️ Divide and conquer
Subtasks can also be extracted into separate classes when designing the API for custom directives. For example, when implementing a tooltip, the core display logic can be defined in the main directive:
@Directive({
selector: '[appTooltip]'
})
export class Tooltip {
open(): void { /* realization */ }
}
And then, specific behavior can be extracted into separate classes, each handling the corresponding events for a particular subtask, applied through an additional selector.
📋 Pseudocode:
@Directive({
selector: '[appTooltip][appTooltipHover]',
host: {
'(mouseenter)': 'tooltip.open()'
}
})
export class TooltipHover {
readonly tooltip = inject(Tooltip);
}
@Directive({
selector: '[appTooltip][appTooltipFocus]',
host: {
'(focus)': 'tooltip.open()'
}
})
export class TooltipFocus {
readonly tooltip = inject(Tooltip);
}
💡 Another conceptual example could be a table header with resize functionality:
<th appHead resizable> ... <th>
In an alternative approach, we could define all the logic within a single class and configure its application using an input:
@Directive({
selector: 'th[appHead]'
})
export class AppTableHeader {
readonly resizable = input(false);
}
However, for complex and optional logic, decomposing it into separate classes and applying them only when needed has significant advantages (unused directives will not be included in the bundle during tree shaking):
@Directive({
selector: 'th[appHead][resizable]'
})
export class AppResizableTableHeader {
/* realization */
}
🚨 Pitfalls
Despite the key advantages of AOP, such as improved modularity, better separation of concerns, and the ability to add new features retrospectively, it also comes with several issues, which can be observed even in Angular’s built-in implementations.
One of these drawbacks is the potential for conflicts between aspects — when multiple aspects are applied to a single point in the code, which can lead to issues with prioritizing their execution. An example of this problem was discussed back in 2015, arising when working with form directives, where Angular creates two different accessors for the same node, both matching the same selector.
Such nuances simply highlight that the approach with aspects should be applied with caution and a clear plan when designing the API for custom directives, where it can be highly effective.
⚠️ The future of selectors
At the time of writing, the Angular team is in the early stages of planning the implementation of selectorless directives. In this API design, a directive can be bound to a node through imports alone (meaning ES module import), without the need for a selector or adding it to the imports list.
Currently, there is no concrete prototype of this functionality. We can also assume that, similar to the introduction of standalone components, directives with selectors will remain backward-compatible, just like NgModules.
Directives and common behavior
Let’s imagine we are developing a UI kit. Despite their diversity, UI components have common points of intersection. Interactive elements exhibit similar state behaviors, while element groups follow a unified theming logic, including appearance variants and color schemes:
As atomic components evolve into a system, automating shared behaviors becomes essential. In addition, this behavior isn’t always limited to conceptually similar elements — sometimes, entirely different components require small cross-cutting logic that inevitably gets repeated.
Inheritance
One solution to unify the common logic could be inheritance. A base class describing a certain behavior pattern with an implementation can be reused by other components.
📋 Pseudocode:
@Directive({
host: {
'[style.--color]': 'this.color()'
}
})
export class ElementBase {
readonly color = input<string>();
// ... and any other logic
}
@Component({...})
export class Button extends ElementBase {}
However, in this case, we are restricted to a single parent class, which often leads to redundant logic for scenarios that not all subclasses require (this is actually one of many issues with inheritance).
Mixins
Angular Material once experimented with a different approach — mixins, which serve as an alternative to inheritance. Here is a code snippet from version 14.2.7:
const _MatButtonBase = mixinColor(
mixinDisabled(
mixinDisableRipple(
class {
constructor(public _elementRef: ElementRef) {}
}
),
),
);
@Component({...})
export class MatButton extends _MatButtonBase {}
Mixins essentially mimic multiple inheritance and solve one of the issues of the previous approach. At the same time, they introduce significant drawbacks, such as difficulties with introspection, typing issues, order of application concerns, and many other pain points (more details).
Composition
For a long time, the existence of directives as separate behavioral aspects has essentially been a tool for implementing reusable behavior. The main obstacle was that directives required explicit binding to a component from the outside:
<app-select [appTheme] [appListboxOwner] />
This, in turn, violates a core principle of components — encapsulation of their internal structure. To preserve this principle, we could create an additional wrapper within the component’s view and apply the directives to this inner node. 📋 Pseudocode:
<!-- usage -->
<app-select />
<!-- select's internal structure -->
<div [appTheme] [appListboxOwner]> <!-- extra node -->
<div>
<div> ... </div>
</div>
</div>
However, this approach is not ideal either, as it forces us to rebind all inputs and outputs for each directive. Moreover, referring to the previous examples in the article, directives are no longer part of the same NodeInjector as the component, which creates obstacles for users when attempting to integrate additional aspects.
⚡ With the release of Angular 15, one of the most revolutionary APIs was introduced — Directive Composition. This API enabled a new approach to component design, allowing developers to focus on the component’s core functionality while delegating the implementation of shared system behavior to host directives. 📋 Pseudocode:
@Component({
hostDirectives: [
{
// I manage the appearance settings
directive: Theme,
inputs: ['variant', 'color']
},
{
// I manage the data of the displayed list
directive: ListboxOwner,
inputs: ['value', 'multiple'],
outputs: ['valueChange']
}
]
})
export class Select {}
In the case of composition, we can declare only the necessary behavioral aspects for the component. Moreover, all exposed input and output properties for each directive can now be directly bound to the component’s node when using it.
Composition and Angular CDK
Thanks to composition, directives serve as “plugins” that we integrate directly during component development. What is especially useful is that these plugins can be ready-made, low-level solutions from the Angular CDK.
For example, when developing a dialog component, we need to consider accessibility requirements, one of which is preventing focus from leaving the dialog area. Angular CDK provides a built-in tool for this in the form of the CdkTrapFocus directive:
import { CdkTrapFocus } from '@angular/cdk/a11y';
@Component({
hostDirectives: [
CdkTrapFocus
]
})
export class Dialog {}
Then, we got the idea to implement dialog dragging. To achieve this, we simply need to add CdkDrag to host directives:
import { CdkDrag } from '@angular/cdk/drag-drop';
@Component({
hostDirectives: [
CdkTrapFocus,
CdkDrag
]
})
export class Dialog {}
Besides the dialog, CdkTrapFocus can be applied to a calendar dropdown component, and CdkDrag can be used for list items where drag-and-drop functionality is required. As already mentioned above, host directives allow us to focus solely on implementing the core functionality, while all other subtasks, such as accessibility, positioning, theming, and so on, are handled by the host directives.
🚧 Despite their powerful capabilities, host directives still have their drawbacks. Configuring such directives from within a component can currently only be done through dependency injection (DI), as there is no built-in mechanism for data binding directly inside the host class.
With Angular CDK, where decorator-based inputs with setters are still used, we can take a workaround approach via DI:
@Component({
hostDirectives: [
{
directive: CdkDrag,
/* ❌ There’s no way to set this value
from within the Dialog component */
inputs: ['rootElementSelector']
}
]
})
export class Dialog {
private readonly drag = inject(CdkDrag);
constructor() {
/* A workaround with DI, assuming the directive still
doesn’t use signal-based inputs or uses model() */
this.drag.rootElementSelector = '.cdk-overlay-pane';
}
}
⚠️ However, once input properties are rewritten as signal-based inputs, we technically won’t be able to set their values by directly accessing the instance object. There is already an open issue in the Angular repository regarding this limitation, which is significant for library developers (😉 you can like the post to draw more attention to the issue or join the discussion).
Conclusion
In this article, we explored the key aspects of working with directives, focusing on their use in system logic. Within each of the described subtopics, there is still plenty of room for more detailed exploration, which will be the subject of separate articles.
As I’ve mentioned several times before in my blog, there is no single correct approach to solving a given problem. Even when it comes to the concepts of inheritance and composition we’ve discussed, each of these solutions is applicable depending on the specific task and context.
The concept of directives is also implemented in other modern frameworks (such as Vue). However, in my experience, directives in Angular are not just a secondary tool, but one of the main pillars of the entire architecture.
Don’t forget to take advantage of Medium’s notification feature to stay updated on new articles if you found this one interesting 🙂
