Angular Best Practices Material

Angular Material Best Practices

Angular Material and CDK rules for component usage, theming, and testing. Use with the core angular-best-practices skill for comprehensive Angular coverage.

Links

• Core Skill: angular-best-practices
• Browse All Skills
• GitHub Repository

When to Apply

• Importing and configuring Material components
• Setting up M3 theming with design tokens
• Using CDK utilities for overlays, drag-and-drop, or virtual scrolling
• Writing tests for Material components

Rules

Install

Install from skills.sh/alfredoperez/angular-best-practices:

• Core skill: angular-best-practices
• This add-on: angular-best-practices-material

Angular Material Best Practices

Use with the core angular-best-practices skill.

---

1. Angular Material

Impact: MEDIUM (UI components)

1.1 Import Angular Material Modules Selectively

Impact: MEDIUM (Reduces bundle size)

Import individual Material component modules (e.g., MatButtonModule) directly in standalone components instead of creating shared material modules. This enables tree-shaking of unused components.

Incorrect:

// shared-material.module.ts — imports everything, tree-shaking fails
@NgModule({ exports: [MatButtonModule, MatCardModule, MatTableModule, /* 30+ modules */] })

Correct:

@Component({
  imports: [MatButtonModule, MatIconModule], // Only what this component needs
})

1.2 Use Angular Material Theming System

Impact: MEDIUM (Consistent design tokens)

Use Material's M3 theming API with mat.theme() to define colors, typography, and density. Create custom themes using CSS custom properties generated by the theme mixin.

Incorrect:

.mat-mdc-button { background: #1976d2; } /* Hardcoded — breaks dark mode */

Correct:

@use '@angular/material' as mat;
html { @include mat.theme((color: (primary: mat.$azure-palette))); }

1.3 Use CDK Utilities Over Custom Implementations

Impact: MEDIUM (Battle-tested, accessible primitives)

Use Angular CDK for overlays (Overlay), drag-and-drop (cdkDrag), virtual scrolling (cdkVirtualFor), clipboard (cdkCopyToClipboard), and accessibility (FocusTrap, LiveAnnouncer) instead of custom solutions.

Incorrect:

// Custom scroll handler — misses edge cases, no recycling
@HostListener('scroll') onScroll() { this.loadMore(); }

Correct:

<cdk-virtual-scroll-viewport itemSize="48">
  <div *cdkVirtualFor="let item of items">{{ item.name }}</div>
</cdk-virtual-scroll-viewport>

1.4 Use Test Harnesses for Material Components

Impact: HIGH (Stable tests across Material versions)

Use Material's built-in test harnesses (MatSelectHarness, MatInputHarness, etc.) instead of querying DOM elements. Harnesses are maintained by the Angular team and survive internal DOM changes.

Incorrect:

const select = fixture.debugElement.query(By.css('.mat-mdc-select'));
select.nativeElement.click(); // Fragile — breaks on Material updates

Correct:

const select = await loader.getHarness(MatSelectHarness.with({ selector: '#role' }));
await select.open();
await select.clickOptions({ text: 'Admin' });

---