Angular UI Patterns

1---
2name: angular-ui-patterns
3description: Modern Angular UI patterns for loading states, error handling, and data display. Use when building UI components, handling async data, or managing component states.
4risk: safe
5source: self
6---
7 
8# Angular UI Patterns
9 
10## Core Principles
11 
121. **Never show stale UI** - Loading states only when actually loading
132. **Always surface errors** - Users must know when something fails
143. **Optimistic updates** - Make the UI feel instant
154. **Progressive disclosure** - Use `@defer` to show content as available
165. **Graceful degradation** - Partial data is better than no data
17 
18---
19 
20## Loading State Patterns
21 
22### The Golden Rule
23 
24**Show loading indicator ONLY when there's no data to display.**
25 
26```typescript
27@Component({
28  template: `
29    @if (error()) {
30      <app-error-state [error]="error()" (retry)="load()" />
31    } @else if (loading() && !items().length) {
32      <app-skeleton-list />
33    } @else if (!items().length) {
34      <app-empty-state message="No items found" />
35    } @else {
36      <app-item-list [items]="items()" />
37    }
38  `,
39})
40export class ItemListComponent {
41  private store = inject(ItemStore);
42 
43  items = this.store.items;
44  loading = this.store.loading;
45  error = this.store.error;
46}
47```
48 
49### Loading State Decision Tree
50 
51```
52Is there an error?
53  → Yes: Show error state with retry option
54  → No: Continue
55 
56Is it loading AND we have no data?
57  → Yes: Show loading indicator (spinner/skeleton)
58  → No: Continue
59 
60Do we have data?
61  → Yes, with items: Show the data
62  → Yes, but empty: Show empty state
63  → No: Show loading (fallback)
64```
65 
66### Skeleton vs Spinner
67 
68| Use Skeleton When    | Use Spinner When      |
69| -------------------- | --------------------- |
70| Known content shape  | Unknown content shape |
71| List/card layouts    | Modal actions         |
72| Initial page load    | Button submissions    |
73| Content placeholders | Inline operations     |
74 
75---
76 
77## Control Flow Patterns
78 
79### @if/@else for Conditional Rendering
80 
81```html
82@if (user(); as user) {
83<span>Welcome, {{ user.name }}</span>
84} @else if (loading()) {
85<app-spinner size="small" />
86} @else {
87<a routerLink="/login">Sign In</a>
88}
89```
90 
91### @for with Track
92 
93```html
94@for (item of items(); track item.id) {
95<app-item-card [item]="item" (delete)="remove(item.id)" />
96} @empty {
97<app-empty-state
98  icon="inbox"
99  message="No items yet"
100  actionLabel="Create Item"
101  (action)="create()"
102/>
103}
104```
105 
106### @defer for Progressive Loading
107 
108```html
109<!-- Critical content loads immediately -->
110<app-header />
111<app-hero-section />
112 
113<!-- Non-critical content deferred -->
114@defer (on viewport) {
115<app-comments [postId]="postId()" />
116} @placeholder {
117<div class="h-32 bg-gray-100 animate-pulse"></div>
118} @loading (minimum 200ms) {
119<app-spinner />
120} @error {
121<app-error-state message="Failed to load comments" />
122}
123```
124 
125---
126 
127## Error Handling Patterns
128 
129### Error Handling Hierarchy
130 
131```
1321. Inline error (field-level) → Form validation errors
1332. Toast notification → Recoverable errors, user can retry
1343. Error banner → Page-level errors, data still partially usable
1354. Full error screen → Unrecoverable, needs user action
136```
137 
138### Always Show Errors
139 
140**CRITICAL: Never swallow errors silently.**
141 
142```typescript
143// CORRECT - Error always surfaced to user
144@Component({...})
145export class CreateItemComponent {
146  private store = inject(ItemStore);
147  private toast = inject(ToastService);
148 
149  async create(data: CreateItemDto) {
150    try {
151      await this.store.create(data);
152      this.toast.success('Item created successfully');
153      this.router.navigate(['/items']);
154    } catch (error) {
155      console.error('createItem failed:', error);
156      this.toast.error('Failed to create item. Please try again.');
157    }
158  }
159}
160 
161// WRONG - Error silently caught
162async create(data: CreateItemDto) {
163  try {
164    await this.store.create(data);
165  } catch (error) {
166    console.error(error); // User sees nothing!
167  }
168}
169```
170 
171### Error State Component Pattern
172 
173```typescript
174@Component({
175  selector: "app-error-state",
176  standalone: true,
177  imports: [NgOptimizedImage],
178  template: `
179    <div class="error-state">
180      <img ngSrc="/assets/error-icon.svg" width="64" height="64" alt="" />
181      <h3>{{ title() }}</h3>
182      <p>{{ message() }}</p>
183      @if (retry.observed) {
184        <button (click)="retry.emit()" class="btn-primary">Try Again</button>
185      }
186    </div>
187  `,
188})
189export class ErrorStateComponent {
190  title = input("Something went wrong");
191  message = input("An unexpected error occurred");
192  retry = output<void>();
193}
194```
195 
196---
197 
198## Button State Patterns
199 
200### Button Loading State
201 
202```html
203<button
204  (click)="handleSubmit()"
205  [disabled]="isSubmitting() || !form.valid"
206  class="btn-primary"
207>
208  @if (isSubmitting()) {
209  <app-spinner size="small" class="mr-2" />
210  Saving... } @else { Save Changes }
211</button>
212```
213 
214### Disable During Operations
215 
216**CRITICAL: Always disable triggers during async operations.**
217 
218```typescript
219// CORRECT - Button disabled while loading
220@Component({
221  template: `
222    <button
223      [disabled]="saving()"
224      (click)="save()"
225    >
226      @if (saving()) {
227        <app-spinner size="sm" /> Saving...
228      } @else {
229        Save
230      }
231    </button>
232  `
233})
234export class SaveButtonComponent {
235  saving = signal(false);
236 
237  async save() {
238    this.saving.set(true);
239    try {
240      await this.service.save();
241    } finally {
242      this.saving.set(false);
243    }
244  }
245}
246 
247// WRONG - User can click multiple times
248<button (click)="save()">
249  {{ saving() ? 'Saving...' : 'Save' }}
250</button>
251```
252 
253---
254 
255## Empty States
256 
257### Empty State Requirements
258 
259Every list/collection MUST have an empty state:
260 
261```html
262@for (item of items(); track item.id) {
263<app-item-card [item]="item" />
264} @empty {
265<app-empty-state
266  icon="folder-open"
267  title="No items yet"
268  description="Create your first item to get started"
269  actionLabel="Create Item"
270  (action)="openCreateDialog()"
271/>
272}
273```
274 
275### Contextual Empty States
276 
277```typescript
278@Component({
279  selector: "app-empty-state",
280  template: `
281    <div class="empty-state">
282      <span class="icon" [class]="icon()"></span>
283      <h3>{{ title() }}</h3>
284      <p>{{ description() }}</p>
285      @if (actionLabel()) {
286        <button (click)="action.emit()" class="btn-primary">
287          {{ actionLabel() }}
288        </button>
289      }
290    </div>
291  `,
292})
293export class EmptyStateComponent {
294  icon = input("inbox");
295  title = input.required<string>();
296  description = input("");
297  actionLabel = input<string | null>(null);
298  action = output<void>();
299}
300```
301 
302---
303 
304## Form Patterns
305 
306### Form with Loading and Validation
307 
308```typescript
309@Component({
310  template: `
311    <form [formGroup]="form" (ngSubmit)="onSubmit()">
312      <div class="form-field">
313        <label for="name">Name</label>
314        <input
315          id="name"
316          formControlName="name"
317          [class.error]="isFieldInvalid('name')"
318        />
319        @if (isFieldInvalid("name")) {
320          <span class="error-text">
321            {{ getFieldError("name") }}
322          </span>
323        }
324      </div>
325 
326      <div class="form-field">
327        <label for="email">Email</label>
328        <input id="email" type="email" formControlName="email" />
329        @if (isFieldInvalid("email")) {
330          <span class="error-text">
331            {{ getFieldError("email") }}
332          </span>
333        }
334      </div>
335 
336      <button type="submit" [disabled]="form.invalid || submitting()">
337        @if (submitting()) {
338          <app-spinner size="sm" /> Submitting...
339        } @else {
340          Submit
341        }
342      </button>
343    </form>
344  `,
345})
346export class UserFormComponent {
347  private fb = inject(FormBuilder);
348 
349  submitting = signal(false);
350 
351  form = this.fb.group({
352    name: ["", [Validators.required, Validators.minLength(2)]],
353    email: ["", [Validators.required, Validators.email]],
354  });
355 
356  isFieldInvalid(field: string): boolean {
357    const control = this.form.get(field);
358    return control ? control.invalid && control.touched : false;
359  }
360 
361  getFieldError(field: string): string {
362    const control = this.form.get(field);
363    if (control?.hasError("required")) return "This field is required";
364    if (control?.hasError("email")) return "Invalid email format";
365    if (control?.hasError("minlength")) return "Too short";
366    return "";
367  }
368 
369  async onSubmit() {
370    if (this.form.invalid) return;
371 
372    this.submitting.set(true);
373    try {
374      await this.service.submit(this.form.value);
375      this.toast.success("Submitted successfully");
376    } catch {
377      this.toast.error("Submission failed");
378    } finally {
379      this.submitting.set(false);
380    }
381  }
382}
383```
384 
385---
386 
387## Dialog/Modal Patterns
388 
389### Confirmation Dialog
390 
391```typescript
392// dialog.service.ts
393@Injectable({ providedIn: 'root' })
394export class DialogService {
395  private dialog = inject(Dialog); // CDK Dialog or custom
396 
397  async confirm(options: {
398    title: string;
399    message: string;
400    confirmText?: string;
401    cancelText?: string;
402  }): Promise<boolean> {
403    const dialogRef = this.dialog.open(ConfirmDialogComponent, {
404      data: options,
405    });
406 
407    return await firstValueFrom(dialogRef.closed) ?? false;
408  }
409}
410 
411// Usage
412async deleteItem(item: Item) {
413  const confirmed = await this.dialog.confirm({
414    title: 'Delete Item',
415    message: `Are you sure you want to delete "${item.name}"?`,
416    confirmText: 'Delete',
417  });
418 
419  if (confirmed) {
420    await this.store.delete(item.id);
421  }
422}
423```
424 
425---
426 
427## Anti-Patterns
428 
429### Loading States
430 
431```typescript
432// WRONG - Spinner when data exists (causes flash on refetch)
433@if (loading()) {
434  <app-spinner />
435}
436 
437// CORRECT - Only show loading without data
438@if (loading() && !items().length) {
439  <app-spinner />
440}
441```
442 
443### Error Handling
444 
445```typescript
446// WRONG - Error swallowed
447try {
448  await this.service.save();
449} catch (e) {
450  console.log(e); // User has no idea!
451}
452 
453// CORRECT - Error surfaced
454try {
455  await this.service.save();
456} catch (e) {
457  console.error("Save failed:", e);
458  this.toast.error("Failed to save. Please try again.");
459}
460```
461 
462### Button States
463 
464```html
465<!-- WRONG - Button not disabled during submission -->
466<button (click)="submit()">Submit</button>
467 
468<!-- CORRECT - Disabled and shows loading -->
469<button (click)="submit()" [disabled]="loading()">
470  @if (loading()) {
471  <app-spinner size="sm" />
472  } Submit
473</button>
474```
475 
476---
477 
478## UI State Checklist
479 
480Before completing any UI component:
481 
482### UI States
483 
484- [ ] Error state handled and shown to user
485- [ ] Loading state shown only when no data exists
486- [ ] Empty state provided for collections (`@empty` block)
487- [ ] Buttons disabled during async operations
488- [ ] Buttons show loading indicator when appropriate
489 
490### Data & Mutations
491 
492- [ ] All async operations have error handling
493- [ ] All user actions have feedback (toast/visual)
494- [ ] Optimistic updates rollback on failure
495 
496### Accessibility
497 
498- [ ] Loading states announced to screen readers
499- [ ] Error messages linked to form fields
500- [ ] Focus management after state changes
501 
502---
503 
504## Integration with Other Skills
505 
506- **angular-state-management**: Use Signal stores for state
507- **angular**: Apply modern patterns (Signals, @defer)
508- **testing-patterns**: Test all UI states
509