name: angular-cdk description: Angular Component Dev Kit (CDK) expertise for building custom components with accessibility, overlays, drag-and-drop, virtual scrolling, and layout utilities. Use when creating custom UI components, implementing accessibility features, building overlays/dialogs, virtual scrolling for large lists, or using CDK utilities for responsive layouts. license: MIT

Angular CDK (Component Dev Kit) Skill

Rules

Lifecycle & Resource Management

Must create FocusTrap in ngOnInit() using focusTrapFactory.create()
Must call focusTrap.focusInitialElement() after creating focus trap
Must destroy FocusTrap in ngOnDestroy() using focusTrap.destroy()
Must stop monitoring focus in ngOnDestroy() using focusMonitor.stopMonitoring()
Must destroy keyManager in ngOnDestroy() using keyManager.destroy()
Must dispose overlayRef in cleanup using overlayRef.dispose()
Must explicitly release all CDK resources in ngOnDestroy()
Must clean up: focusTrap, overlayRef, focusMonitor, keyManager
Shall Not leave CDK resources without cleanup (causes memory leaks)

Accessibility

Must use LiveAnnouncer for screen reader announcements of dynamic content
Must use FocusKeyManager for keyboard navigation in lists

Overlay Positioning

Must use flexibleConnectedTo() with at least two fallback position strategies
Must configure explicit scrollStrategy for overlay
Must configure explicit hasBackdrop property for overlay
Must attach portal to overlay using overlayRef.attach(portal)

Portal Usage

Must use ComponentPortal for dynamic component rendering
Must use TemplatePortal for template content projection
Must detach portal when no longer needed to prevent memory leaks

Drag & Drop

Must use cdkDropList container with (cdkDropListDropped) event handler
Must use cdkDrag directive on draggable items
Must use track expressions in @for loops with drag items
Must use moveItemInArray() for single-list reordering
Must use transferArrayItem() for cross-list transfers
Must connect drop lists using [cdkDropListConnectedTo] for cross-list drag

Virtual Scrolling

Only use CdkVirtualScrollViewport for lists with more than 100 items
Must set explicit itemSize property
Must configure minBufferPx and maxBufferPx for smooth scrolling
Must set fixed height on viewport container
Must Not use auto-height virtual scroll viewports

Breakpoint Observer

Must use BreakpointObserver for responsive layout detection
Must use toSignal() when converting breakpoint observables to signals
Must provide initialValue when using toSignal() with breakpoints
Must Not use direct window.innerWidth or manual resize listeners
Must Not use direct window.matchMedia() calls

Context

🎯 Purpose

This skill provides comprehensive guidance on the Angular Component Dev Kit (CDK), a set of behavior primitives for building accessible, high-quality Angular components without Material Design styling.

📦 What is Angular CDK?

The Angular CDK is a library of unstyled UI component behaviors:

Accessibility (A11y): Screen reader support, keyboard navigation, focus management
Overlay: Positioning, backdrop, and overlay management
Portal: Dynamic component rendering
Drag & Drop: Sortable lists and drag-and-drop interactions
Virtual Scrolling: Efficient rendering of large lists
Layout: Responsive layout utilities and breakpoint observers
Table: Data table functionality without styling
Tree: Hierarchical tree structures

🎨 When to Use This Skill

Use Angular CDK guidance when:

Building custom UI components from scratch
Implementing accessible components (ARIA, focus management)
Creating overlays, modals, or tooltips
Building drag-and-drop functionality
Implementing virtual scrolling for performance
Working with responsive layouts and breakpoints
Creating custom data tables or tree views
Managing focus trapping and keyboard navigation

📚 Core CDK Modules

1. Accessibility (A11y)

Focus Management:

import { FocusTrapFactory, FocusMonitor } from '@angular/cdk/a11y';

export class DialogComponent implements OnInit, OnDestroy {
  private focusTrap: FocusTrap;
  
  constructor(
    private focusTrapFactory: FocusTrapFactory,
    private focusMonitor: FocusMonitor,
    private elementRef: ElementRef
  ) {}
  
  ngOnInit() {
    // Create focus trap to keep focus within dialog
    this.focusTrap = this.focusTrapFactory.create(
      this.elementRef.nativeElement
    );
    this.focusTrap.focusInitialElement();
    
    // Monitor focus changes
    this.focusMonitor.monitor(this.elementRef, true).subscribe(origin => {
      console.log('Focus origin:', origin);
    });
  }
  
  ngOnDestroy() {
    this.focusTrap.destroy();
    this.focusMonitor.stopMonitoring(this.elementRef);
  }
}

Live Announcer (Screen Readers):

import { LiveAnnouncer } from '@angular/cdk/a11y';

export class NotificationComponent {
  constructor(private liveAnnouncer: LiveAnnouncer) {}
  
  announce(message: string) {
    // Announce to screen readers
    this.liveAnnouncer.announce(message, 'polite');
  }
  
  announceUrgent(message: string) {
    this.liveAnnouncer.announce(message, 'assertive');
  }
}

List Key Manager (Keyboard Navigation):

import { FocusKeyManager } from '@angular/cdk/a11y';
import { QueryList, ViewChildren, AfterViewInit } from '@angular/core';

export class MenuComponent implements AfterViewInit {
  @ViewChildren(MenuItem) menuItems: QueryList<MenuItem>;
  private keyManager: FocusKeyManager<MenuItem>;
  
  ngAfterViewInit() {
    this.keyManager = new FocusKeyManager(this.menuItems)
      .withWrap()
      .withVerticalOrientation();
  }
  
  onKeydown(event: KeyboardEvent) {
    this.keyManager.onKeydown(event);
  }
}

2. Overlay

Creating Overlays:

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal } from '@angular/cdk/portal';

export class TooltipDirective {
  private overlayRef: OverlayRef | null = null;
  
  constructor(
    private overlay: Overlay,
    private elementRef: ElementRef
  ) {}
  
  show() {
    // Create overlay configuration
    const config = new OverlayConfig({
      positionStrategy: this.overlay.position()
        .flexibleConnectedTo(this.elementRef)
        .withPositions([
          {
            originX: 'center',
            originY: 'bottom',
            overlayX: 'center',
            overlayY: 'top',
            offsetY: 8
          }
        ]),
      hasBackdrop: false,
      scrollStrategy: this.overlay.scrollStrategies.reposition()
    });
    
    // Create overlay
    this.overlayRef = this.overlay.create(config);
    
    // Attach component to overlay
    const portal = new ComponentPortal(TooltipComponent);
    this.overlayRef.attach(portal);
  }
  
  hide() {
    if (this.overlayRef) {
      this.overlayRef.dispose();
      this.overlayRef = null;
    }
  }
}

Global Position Strategy:

const config = new OverlayConfig({
  positionStrategy: this.overlay.position()
    .global()
    .centerHorizontally()
    .centerVertically(),
  hasBackdrop: true,
  backdropClass: 'dark-backdrop'
});

3. Portal

Template Portals:

import { TemplatePortal } from '@angular/cdk/portal';
import { TemplateRef, ViewContainerRef } from '@angular/core';

export class PortalExample {
  @ViewChild('templatePortalContent') templateRef: TemplateRef<any>;
  selectedPortal: TemplatePortal<any>;
  
  constructor(private viewContainerRef: ViewContainerRef) {}
  
  createTemplatePortal() {
    this.selectedPortal = new TemplatePortal(
      this.templateRef,
      this.viewContainerRef
    );
  }
}

<ng-template #templatePortalContent>
  <p>This content will be rendered in a portal</p>
</ng-template>

<div cdkPortalOutlet [cdkPortalOutlet]="selectedPortal"></div>

Component Portals:

import { ComponentPortal } from '@angular/cdk/portal';

createComponentPortal() {
  const portal = new ComponentPortal(
    MyComponent,
    null, // ViewContainerRef (optional)
    this.injector, // Custom injector (optional)
    this.componentFactoryResolver // (optional)
  );
  
  // Attach to overlay or portal outlet
  const ref = this.overlayRef.attach(portal);
  ref.instance.data = 'Custom data';
}

4. Drag & Drop

Sortable List:

import { CdkDragDrop, moveItemInArray } from '@angular/cdk/drag-drop';

@Component({
  template: `
    <div cdkDropList (cdkDropListDropped)="drop($event)">
      @for (item of items; track item) {
        <div cdkDrag>
          <div class="drag-handle" cdkDragHandle>⋮⋮</div>
          {{ item }}
        </div>
      }
    </div>
  `
})
export class SortableListComponent {
  items = ['Item 1', 'Item 2', 'Item 3'];
  
  drop(event: CdkDragDrop<string[]>) {
    moveItemInArray(this.items, event.previousIndex, event.currentIndex);
  }
}

Drag Between Lists:

import { CdkDragDrop, transferArrayItem } from '@angular/cdk/drag-drop';

@Component({
  template: `
    <div class="lists-container">
      <div cdkDropList #todoList="cdkDropList"
           [cdkDropListData]="todo"
           [cdkDropListConnectedTo]="[doneList]"
           (cdkDropListDropped)="drop($event)">
        @for (item of todo; track item) {
          <div cdkDrag>{{ item }}</div>
        }
      </div>
      
      <div cdkDropList #doneList="cdkDropList"
           [cdkDropListData]="done"
           [cdkDropListConnectedTo]="[todoList]"
           (cdkDropListDropped)="drop($event)">
        @for (item of done; track item) {
          <div cdkDrag>{{ item }}</div>
        }
      </div>
    </div>
  `
})
export class TaskBoardComponent {
  todo = ['Task 1', 'Task 2'];
  done = ['Task 3'];
  
  drop(event: CdkDragDrop<string[]>) {
    if (event.previousContainer === event.container) {
      moveItemInArray(event.container.data, event.previousIndex, event.currentIndex);
    } else {
      transferArrayItem(
        event.previousContainer.data,
        event.container.data,
        event.previousIndex,
        event.currentIndex
      );
    }
  }
}

5. Virtual Scrolling

Virtual Scroll for Large Lists:

import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';

@Component({
  template: `
    <cdk-virtual-scroll-viewport itemSize="50" class="viewport">
      @for (item of items; track item) {
        <div class="item">{{ item }}</div>
      }
    </cdk-virtual-scroll-viewport>
  `,
  styles: [`
    .viewport {
      height: 400px;
      width: 100%;
    }
    
    .item {
      height: 50px;
      display: flex;
      align-items: center;
    }
  `]
})
export class VirtualScrollComponent {
  items = Array.from({ length: 10000 }, (_, i) => `Item #${i}`);
}

Dynamic Item Sizes:

@Component({
  template: `
    <cdk-virtual-scroll-viewport 
      [itemSize]="50" 
      minBufferPx="200" 
      maxBufferPx="400">
      @for (item of items; track item.id) {
        <div class="item" [style.height.px]="item.height">
          {{ item.content }}
        </div>
      }
    </cdk-virtual-scroll-viewport>
  `
})
export class DynamicVirtualScrollComponent {
  items = Array.from({ length: 1000 }, (_, i) => ({
    id: i,
    content: `Item ${i}`,
    height: 40 + (i % 3) * 20 // Variable heights
  }));
}

6. Layout & Breakpoints

Breakpoint Observer:

import { BreakpointObserver, Breakpoints } from '@angular/cdk/layout';

export class ResponsiveComponent {
  isHandset$ = this.breakpointObserver.observe(Breakpoints.Handset)
    .pipe(map(result => result.matches));
  
  constructor(private breakpointObserver: BreakpointObserver) {
    // Observe multiple breakpoints
    this.breakpointObserver.observe([
      Breakpoints.XSmall,
      Breakpoints.Small,
      Breakpoints.Medium,
      Breakpoints.Large,
      Breakpoints.XLarge
    ]).subscribe(result => {
      if (result.breakpoints[Breakpoints.XSmall]) {
        this.columns = 1;
      } else if (result.breakpoints[Breakpoints.Small]) {
        this.columns = 2;
      } else {
        this.columns = 4;
      }
    });
  }
}

Custom Breakpoints:

const customBreakpoints = {
  mobile: '(max-width: 599px)',
  tablet: '(min-width: 600px) and (max-width: 959px)',
  desktop: '(min-width: 960px)'
};

this.breakpointObserver.observe([customBreakpoints.mobile])
  .subscribe(result => {
    this.isMobile = result.matches;
  });

7. Table

CDK Table (Unstyled):

import { DataSource } from '@angular/cdk/collections';

@Component({
  template: `
    <cdk-table [dataSource]="dataSource">
      <ng-container cdkColumnDef="name">
        <cdk-header-cell *cdkHeaderCellDef>Name</cdk-header-cell>
        <cdk-cell *cdkCellDef="let row">{{ row.name }}</cdk-cell>
      </ng-container>
      
      <ng-container cdkColumnDef="email">
        <cdk-header-cell *cdkHeaderCellDef>Email</cdk-header-cell>
        <cdk-cell *cdkCellDef="let row">{{ row.email }}</cdk-cell>
      </ng-container>
      
      <cdk-header-row *cdkHeaderRowDef="displayedColumns"></cdk-header-row>
      <cdk-row *cdkRowDef="let row; columns: displayedColumns;"></cdk-row>
    </cdk-table>
  `
})
export class TableComponent {
  displayedColumns = ['name', 'email'];
  dataSource = new MyDataSource();
}

8. Tree

Nested Tree:

import { NestedTreeControl } from '@angular/cdk/tree';
import { ArrayDataSource } from '@angular/cdk/collections';

interface FileNode {
  name: string;
  children?: FileNode[];
}

@Component({
  template: `
    <cdk-tree [dataSource]="dataSource" [treeControl]="treeControl">
      <cdk-nested-tree-node *cdkTreeNodeDef="let node">
        {{ node.name }}
      </cdk-nested-tree-node>
      
      <cdk-nested-tree-node *cdkTreeNodeDef="let node; when: hasChild">
        <button (click)="treeControl.toggle(node)">
          {{ treeControl.isExpanded(node) ? '▼' : '▶' }}
        </button>
        {{ node.name }}
        
        <div *ngIf="treeControl.isExpanded(node)">
          <ng-container cdkTreeNodeOutlet></ng-container>
        </div>
      </cdk-nested-tree-node>
    </cdk-tree>
  `
})
export class TreeComponent {
  treeControl = new NestedTreeControl<FileNode>(node => node.children);
  dataSource = new ArrayDataSource(TREE_DATA);
  
  hasChild = (_: number, node: FileNode) => !!node.children && node.children.length > 0;
}

🎯 Best Practices

1. Accessibility First

// Always use CDK a11y utilities for custom components
import { FocusTrap, LiveAnnouncer } from '@angular/cdk/a11y';

// Trap focus in modals
// Announce dynamic content changes
// Implement keyboard navigation

2. Overlay Positioning

// Use flexible positioning for better UX
const positionStrategy = this.overlay.position()
  .flexibleConnectedTo(this.elementRef)
  .withPositions([
    // Primary position
    { originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'top' },
    // Fallback positions
    { originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'bottom' },
    { originX: 'end', originY: 'bottom', overlayX: 'end', overlayY: 'top' }
  ]);

3. Virtual Scrolling Performance

// Configure buffer sizes for smooth scrolling
<cdk-virtual-scroll-viewport 
  itemSize="50"
  minBufferPx="400"   // Render extra items above
  maxBufferPx="800">  // Render extra items below

4. Drag & Drop Constraints

// Constrain drag movement
<div cdkDrag [cdkDragBoundary]="'.boundary-element'">
  Constrained drag
</div>

// Custom drag preview
<div cdkDrag>
  <div *cdkDragPreview>Custom preview</div>
  <div *cdkDragPlaceholder>Placeholder</div>
  Content
</div>

🐛 Troubleshooting

Issue	Solution
Overlay not positioning correctly	Check scroll strategy and position preferences
Virtual scroll not rendering	Ensure `itemSize` matches actual item height
Drag & drop not working	Import `DragDropModule` and use correct directives
Focus trap not working	Ensure element has focusable children
Breakpoint observer not triggering	Check for correct breakpoint strings
Tree not expanding	Implement `hasChild` function and tree control

📖 References

💡 Common Use Cases

Custom Dropdown: Use Overlay + Portal
Accessible Dialog: Use Overlay + Focus Trap + Live Announcer
Infinite Scroll: Use Virtual Scroll Viewport
Sortable Table: Use CDK Table + Drag Drop
Responsive Sidebar: Use Breakpoint Observer + Layout
File Tree: Use CDK Tree
Custom Tooltip: Use Overlay + Positioning Strategy

📂 Recommended Placement

Project-level skill:

/.github/skills/angular-cdk/SKILL.md

Copilot will load this when working with Angular CDK features.

angular-cdk

SKILL.md