Agent skill
angular-directives
Create custom directives in Angular v20+ for DOM manipulation and behavior extension. Use for attribute directives that modify element behavior/appearance, structural directives for portals/overlays, and host directives for composition. Triggers on creating reusable DOM behaviors, extending element functionality, or composing behaviors across components. Note - use native @if/@for/@switch for control flow, not custom structural directives.
Install this agent skill to your Project
npx add-skill https://github.com/analogjs/angular-skills/tree/main/skills/angular-directives
SKILL.md
Angular Directives
Create custom directives for reusable DOM manipulation and behavior in Angular v20+.
Attribute Directives
Modify the appearance or behavior of an element:
import { Directive, input, effect, inject, ElementRef } from '@angular/core';
@Directive({
selector: '[appHighlight]',
})
export class Highlight {
private el = inject(ElementRef<HTMLElement>);
// Input with alias matching selector
color = input('yellow', { alias: 'appHighlight' });
constructor() {
effect(() => {
this.el.nativeElement.style.backgroundColor = this.color();
});
}
}
// Usage: <p appHighlight="lightblue">Highlighted text</p>
// Usage: <p appHighlight>Default yellow highlight</p>
Using host Property
Prefer host over @HostBinding/@HostListener:
@Directive({
selector: '[appTooltip]',
host: {
'(mouseenter)': 'show()',
'(mouseleave)': 'hide()',
'[attr.aria-describedby]': 'tooltipId',
},
})
export class Tooltip {
text = input.required<string>({ alias: 'appTooltip' });
position = input<'top' | 'bottom' | 'left' | 'right'>('top');
tooltipId = `tooltip-${crypto.randomUUID()}`;
private tooltipEl: HTMLElement | null = null;
private el = inject(ElementRef<HTMLElement>);
show() {
this.tooltipEl = document.createElement('div');
this.tooltipEl.id = this.tooltipId;
this.tooltipEl.className = `tooltip tooltip-${this.position()}`;
this.tooltipEl.textContent = this.text();
this.tooltipEl.setAttribute('role', 'tooltip');
document.body.appendChild(this.tooltipEl);
this.positionTooltip();
}
hide() {
this.tooltipEl?.remove();
this.tooltipEl = null;
}
private positionTooltip() {
// Position logic based on this.position() and this.el
}
}
// Usage: <button appTooltip="Click to save" position="bottom">Save</button>
Class and Style Manipulation
@Directive({
selector: '[appButton]',
host: {
'class': 'btn',
'[class.btn-primary]': 'variant() === "primary"',
'[class.btn-secondary]': 'variant() === "secondary"',
'[class.btn-sm]': 'size() === "small"',
'[class.btn-lg]': 'size() === "large"',
'[class.disabled]': 'disabled()',
'[attr.disabled]': 'disabled() || null',
},
})
export class Button {
variant = input<'primary' | 'secondary'>('primary');
size = input<'small' | 'medium' | 'large'>('medium');
disabled = input(false, { transform: booleanAttribute });
}
// Usage: <button appButton variant="primary" size="large">Click</button>
Event Handling
@Directive({
selector: '[appClickOutside]',
host: {
'(document:click)': 'onDocumentClick($event)',
},
})
export class ClickOutside {
private el = inject(ElementRef<HTMLElement>);
clickOutside = output<void>();
onDocumentClick(event: MouseEvent) {
if (!this.el.nativeElement.contains(event.target as Node)) {
this.clickOutside.emit();
}
}
}
// Usage: <div appClickOutside (clickOutside)="closeMenu()">...</div>
Keyboard Shortcuts
@Directive({
selector: '[appShortcut]',
host: {
'(document:keydown)': 'onKeydown($event)',
},
})
export class Shortcut {
key = input.required<string>({ alias: 'appShortcut' });
ctrl = input(false, { transform: booleanAttribute });
shift = input(false, { transform: booleanAttribute });
alt = input(false, { transform: booleanAttribute });
triggered = output<KeyboardEvent>();
onKeydown(event: KeyboardEvent) {
const keyMatch = event.key.toLowerCase() === this.key().toLowerCase();
const ctrlMatch = this.ctrl() ? event.ctrlKey || event.metaKey : !event.ctrlKey && !event.metaKey;
const shiftMatch = this.shift() ? event.shiftKey : !event.shiftKey;
const altMatch = this.alt() ? event.altKey : !event.altKey;
if (keyMatch && ctrlMatch && shiftMatch && altMatch) {
event.preventDefault();
this.triggered.emit(event);
}
}
}
// Usage: <button appShortcut="s" ctrl (triggered)="save()">Save (Ctrl+S)</button>
Structural Directives
Use structural directives for DOM manipulation beyond control flow (portals, overlays, dynamic insertion points). For conditionals and loops, use native @if, @for, @switch.
Portal Directive
Render content in a different DOM location:
import { Directive, inject, TemplateRef, ViewContainerRef, OnInit, OnDestroy, input } from '@angular/core';
@Directive({
selector: '[appPortal]',
})
export class Portal implements OnInit, OnDestroy {
private templateRef = inject(TemplateRef<any>);
private viewContainerRef = inject(ViewContainerRef);
private viewRef: EmbeddedViewRef<any> | null = null;
// Target container selector or element
target = input<string | HTMLElement>('body', { alias: 'appPortal' });
ngOnInit() {
const container = this.getContainer();
if (container) {
this.viewRef = this.viewContainerRef.createEmbeddedView(this.templateRef);
this.viewRef.rootNodes.forEach(node => container.appendChild(node));
}
}
ngOnDestroy() {
this.viewRef?.destroy();
}
private getContainer(): HTMLElement | null {
const target = this.target();
if (typeof target === 'string') {
return document.querySelector(target);
}
return target;
}
}
// Usage: Render modal at body level
// <div *appPortal="'body'">
// <div class="modal">Modal content</div>
// </div>
Lazy Render Directive
Defer rendering until condition is met (one-time):
@Directive({
selector: '[appLazyRender]',
})
export class LazyRender {
private templateRef = inject(TemplateRef<any>);
private viewContainer = inject(ViewContainerRef);
private rendered = false;
condition = input.required<boolean>({ alias: 'appLazyRender' });
constructor() {
effect(() => {
// Only render once when condition becomes true
if (this.condition() && !this.rendered) {
this.viewContainer.createEmbeddedView(this.templateRef);
this.rendered = true;
}
});
}
}
// Usage: Render heavy component only when tab is first activated
// <div *appLazyRender="activeTab() === 'reports'">
// <app-heavy-reports />
// </div>
Template Outlet with Context
interface TemplateContext<T> {
$implicit: T;
item: T;
index: number;
}
@Directive({
selector: '[appTemplateOutlet]',
})
export class TemplateOutlet<T> {
private viewContainer = inject(ViewContainerRef);
private currentView: EmbeddedViewRef<TemplateContext<T>> | null = null;
template = input.required<TemplateRef<TemplateContext<T>>>({ alias: 'appTemplateOutlet' });
context = input.required<T>({ alias: 'appTemplateOutletContext' });
index = input(0, { alias: 'appTemplateOutletIndex' });
constructor() {
effect(() => {
const template = this.template();
const context = this.context();
const index = this.index();
if (this.currentView) {
this.currentView.context.$implicit = context;
this.currentView.context.item = context;
this.currentView.context.index = index;
this.currentView.markForCheck();
} else {
this.currentView = this.viewContainer.createEmbeddedView(template, {
$implicit: context,
item: context,
index,
});
}
});
}
}
// Usage: Custom list with template
// <ng-template #itemTemplate let-item let-i="index">
// <div>{{ i }}: {{ item.name }}</div>
// </ng-template>
// <ng-container
// *appTemplateOutlet="itemTemplate; context: item; index: i"
// />
Host Directives
Compose directives on components or other directives:
// Reusable behavior directives
@Directive({
selector: '[focusable]',
host: {
'tabindex': '0',
'(focus)': 'onFocus()',
'(blur)': 'onBlur()',
'[class.focused]': 'isFocused()',
},
})
export class Focusable {
isFocused = signal(false);
onFocus() { this.isFocused.set(true); }
onBlur() { this.isFocused.set(false); }
}
@Directive({
selector: '[disableable]',
host: {
'[class.disabled]': 'disabled()',
'[attr.aria-disabled]': 'disabled()',
},
})
export class Disableable {
disabled = input(false, { transform: booleanAttribute });
}
// Component using host directives
@Component({
selector: 'app-custom-button',
hostDirectives: [
Focusable,
{
directive: Disableable,
inputs: ['disabled'],
},
],
host: {
'role': 'button',
'(click)': 'onClick($event)',
'(keydown.enter)': 'onClick($event)',
'(keydown.space)': 'onClick($event)',
},
template: `<ng-content />`,
})
export class CustomButton {
private disableable = inject(Disableable);
clicked = output<void>();
onClick(event: Event) {
if (!this.disableable.disabled()) {
this.clicked.emit();
}
}
}
// Usage: <app-custom-button disabled>Click me</app-custom-button>
Exposing Host Directive Outputs
@Directive({
selector: '[hoverable]',
host: {
'(mouseenter)': 'onEnter()',
'(mouseleave)': 'onLeave()',
'[class.hovered]': 'isHovered()',
},
})
export class Hoverable {
isHovered = signal(false);
hoverChange = output<boolean>();
onEnter() {
this.isHovered.set(true);
this.hoverChange.emit(true);
}
onLeave() {
this.isHovered.set(false);
this.hoverChange.emit(false);
}
}
@Component({
selector: 'app-card',
hostDirectives: [
{
directive: Hoverable,
outputs: ['hoverChange'],
},
],
template: `<ng-content />`,
})
export class Card {}
// Usage: <app-card (hoverChange)="onHover($event)">...</app-card>
Directive Composition API
Combine multiple behaviors:
// Base directives
@Directive({ selector: '[withRipple]' })
export class Ripple {
// Ripple effect implementation
}
@Directive({ selector: '[withElevation]' })
export class Elevation {
elevation = input(2);
}
// Composed component
@Component({
selector: 'app-material-button',
hostDirectives: [
Ripple,
{
directive: Elevation,
inputs: ['elevation'],
},
{
directive: Disableable,
inputs: ['disabled'],
},
],
template: `<ng-content />`,
})
export class MaterialButton {}
For advanced patterns, see references/directive-patterns.md.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
analogjs/angular-skills
angular-http
Implement HTTP data fetching in Angular v20+ using resource(), httpResource(), and HttpClient. Use for API calls, data loading with signals, request/response handling, and interceptors. Triggers on data fetching, API integration, loading states, error handling, or converting Observable-based HTTP to signal-based patterns.
analogjs/angular-skills
angular-routing
Implement routing in Angular v20+ applications with lazy loading, functional guards, resolvers, and route parameters. Use for navigation setup, protected routes, route-based data loading, and nested routing. Triggers on route configuration, adding authentication guards, implementing lazy loading, or reading route parameters with signals.
analogjs/angular-skills
angular-testing
Write unit and integration tests for Angular v20+ applications using Vitest or Jasmine with TestBed and modern testing patterns. Use for testing components with signals, OnPush change detection, services with inject(), and HTTP interactions. Triggers on test creation, testing signal-based components, mocking dependencies, or setting up test infrastructure. Don't use for E2E testing with Cypress or Playwright, or for testing non-Angular JavaScript/TypeScript code.
analogjs/angular-skills
angular-forms
Build signal-based forms in Angular v21+ using the new Signal Forms API. Use for form creation with automatic two-way binding, schema-based validation, field state management, and dynamic forms. Triggers on form implementation, adding validation, creating multi-step forms, or building forms with conditional fields. Signal Forms are experimental but recommended for new Angular projects. Don't use for template-driven forms without signals or third-party form libraries like Formly or ngx-formly.
analogjs/angular-skills
angular-signals
Implement signal-based reactive state management in Angular v20+. Use for creating reactive state with signal(), derived state with computed(), dependent state with linkedSignal(), and side effects with effect(). Triggers on state management questions, converting from BehaviorSubject/Observable patterns to signals, or implementing reactive data flows.
analogjs/angular-skills
angular-ssr
Implement server-side rendering and hydration in Angular v20+ using @angular/ssr. Use for SSR setup, hydration strategies, prerendering static pages, and handling browser-only APIs. Triggers on SSR configuration, fixing hydration mismatches, prerendering routes, or making code SSR-compatible.
Didn't find tool you were looking for?