Alert Component

A flexible alert component built with Angular that provides a way to display notification messages with multiple variants, dismissible functionality, and icon integration. The component follows the shadcn/ui design principles and is fully customizable with modern signal-based reactivity.

Official Documentation

Features

• 🎨 Multiple Variants: Default, destructive, warning, success, and info styles with proper dark mode support
• ❌ Dismissible: Optional close button functionality with fade and collapse animations
• 🔧 Composition: Built with separate components for title, content, icon, and action
• 🎯 Accessibility: Proper ARIA attributes, screen reader support, and keyboard navigation
• 📝 Rich Content: Support for titles, descriptions, and action buttons
• 🎭 Customizable: Additional CSS classes and styling options
• ⚡ Performance: Signal-based reactivity with OnPush change detection
• 🎪 Animations: Smooth fade and collapse animations when dismissing
• ⌨️ Keyboard Navigation: Full keyboard support for interactive elements
• 🎯 Type-Safe: Complete TypeScript support with proper type definitions

Installation

Step 1: Install the CLI

First, install the ng-shangjc CLI globally or use npx:

# Install globally
npm install -g @ng-shangjc/cli

# or with yarn
yarn global add @ng-shangjc/cli

# or with pnpm
pnpm install -g @ng-shangjc/cli

# Or use npx without installation
npx @ng-shangjc/cli <command>

Step 2: Initialize your project

If you haven't already, initialize your Angular project for ng-shangjc components:

ng-shangjc init

This will create a shangjc.config.json file and set up your project for component installations.

Step 3: Install the component

Install the alert component into your project:

ng-shangjc install alert

The component will be installed in the configured path (default: src/ui/shangjc). Adjust the import path in your components based on your project structure and the configured installation path.

Import

After installation, import the components from your configured installation path. The examples below use the default path src/ui/shangjc - adjust the path according to your project structure and configuration.

Standalone Components (Recommended)

Import and use the individual components directly in your standalone components:

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { 
  AlertComponent,
  AlertTitleComponent,
  AlertContentComponent,
  AlertActionComponent,
  AlertIconComponent
} from './ui/shangjc/alert';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    AlertComponent,
    AlertTitleComponent,
    AlertContentComponent,
    AlertActionComponent,
    AlertIconComponent
  ],
  template: `
    <ng-shangjc-alert variant="success">
      <ng-shangjc-alert-title>Success!</ng-shangjc-alert-title>
      <ng-shangjc-alert-content>Your action was completed successfully.</ng-shangjc-alert-content>
      <ng-shangjc-alert-action (onClick)="onAction()">Undo</ng-shangjc-alert-action>
    </ng-shangjc-alert>
  `
})
export class ExampleComponent {
  onAction() {
    console.log('Action clicked!');
  }
}

Using NgModule (Legacy)

If you're using NgModules, import the AlertModule:

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { AlertModule } from './ui/shangjc/alert';

@NgModule({
  declarations: [YourComponent],
  imports: [
    CommonModule,
    AlertModule
  ]
})
export class YourModule { }

Then use the components in your templates:

<ng-shangjc-alert>
  <!-- Component content -->
</ng-shangjc-alert>

Basic Usage

Default Example

import { Component } from '@angular/core';
import { 
  AlertComponent,
  AlertTitleComponent,
  AlertContentComponent,
  AlertActionComponent,
  AlertIconComponent
} from './ui/shangjc/alert';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    AlertComponent,
    AlertTitleComponent,
    AlertContentComponent,
    AlertActionComponent,
    AlertIconComponent
  ],
  template: `
    <ng-shangjc-alert variant="success">
      <ng-shangjc-alert-title>Success!</ng-shangjc-alert-title>
      <ng-shangjc-alert-content>Your action was completed successfully.</ng-shangjc-alert-content>
      <ng-shangjc-alert-action (onClick)="onAction()">Undo</ng-shangjc-alert-action>
    </ng-shangjc-alert>
  `
})
export class ExampleComponent {
  onAction() {
    console.log('Action clicked!');
  }
}

Alternative Usage Patterns

Different Variants

<!-- Default -->
<ng-shangjc-alert>
  <ng-shangjc-alert-content>Default alert for general information.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Destructive -->
<ng-shangjc-alert variant="destructive">
  <ng-shangjc-alert-content>Error alert for critical issues.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Warning -->
<ng-shangjc-alert variant="warning">
  <ng-shangjc-alert-content>Warning alert for important notices.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Success -->
<ng-shangjc-alert variant="success">
  <ng-shangjc-alert-content>Success alert for completed actions.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Info -->
<ng-shangjc-alert variant="info">
  <ng-shangjc-alert-content>Info alert for helpful information.</ng-shangjc-alert-content>
</ng-shangjc-alert>

Dismissible Alerts

<!-- With fade animation -->
<ng-shangjc-alert 
  variant="info" 
  [dismissible]="true"
  [fade]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will fade out when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- With collapse animation -->
<ng-shangjc-alert 
  variant="warning" 
  [dismissible]="true"
  [collapse]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will collapse when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Without animation -->
<ng-shangjc-alert 
  variant="success"
  [dismissible]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will be hidden immediately when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

Custom Icons

<ng-shangjc-alert variant="success">
  <ng-shangjc-alert-icon>
    <svg class="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
      <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
    </svg>
  </ng-shangjc-alert-icon>
  <ng-shangjc-alert-content>Custom success icon alert.</ng-shangjc-alert-content>
</ng-shangjc-alert>

Advanced Usage

Controlled Component

import { Component, signal } from '@angular/core';
import { AlertComponent } from './ui/shangjc/alert';

@Component({
  selector: 'app-controlled-example',
  standalone: true,
  imports: [AlertComponent],
  template: `
    <ng-shangjc-alert 
      variant="info" 
      [dismissible]="true"
      (dismissed)="onDismissed()"
      #alertRef>
      <ng-shangjc-alert-content>
        This is a controlled alert with dismiss functionality.
      </ng-shangjc-alert-content>
    </ng-shangjc-alert>
    
    <button (click)="alertRef.dismiss()">Dismiss Programmatically</button>
  `
})
export class ControlledExampleComponent {
  isDismissed = signal(false);
  
  onDismissed() {
    this.isDismissed.set(true);
    console.log('Alert was dismissed');
  }
}

Complex Alert with Multiple Actions

<ng-shangjc-alert variant="warning">
  <ng-shangjc-alert-title>Update Available</ng-shangjc-alert-title>
  <ng-shangjc-alert-content>
    A new version of the application is available. Would you like to update now?
  </ng-shangjc-alert-content>
  <div class="mt-2 flex gap-2">
    <ng-shangjc-alert-action (onClick)="updateNow()">Update Now</ng-shangjc-alert-action>
    <ng-shangjc-alert-action (onClick)="learnMore()">Learn More</ng-shangjc-alert-action>
  </div>
</ng-shangjc-alert>

Form Validation Integration

<ng-shangjc-alert variant="destructive" [dismissible]="true">
  <ng-shangjc-alert-title>Validation Error</ng-shangjc-alert-title>
  <ng-shangjc-alert-content>
    <ul class="mt-2 list-disc list-inside">
      <li>Email is required</li>
      <li>Password must be at least 8 characters</li>
    </ul>
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

API Reference

AlertComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | variant | 'default' \| 'destructive' \| 'warning' \| 'success' \| 'info' | 'default' | Alert style variant | | dismissible | boolean | false | Whether the alert can be dismissed | | fade | boolean | false | Whether to use fade animation when dismissing | | collapse | boolean | false | Whether to use collapse animation when dismissing | | showIcon | boolean | true | Whether to show the default variant icon | | class | string | '' | Additional CSS classes | | ariaLive | 'polite' \| 'assertive' \| 'off' | 'polite' | ARIA live region behavior | | ariaAtomic | boolean | true | ARIA atomic attribute | | ariaLabel | string | undefined | ARIA label for the alert | | ariaDescribedBy | string | undefined | ARIA described by for the alert | | role | string | 'alert' | ARIA role for the alert | | dismissed | EventEmitter<void> | - | Emitted when alert is dismissed | | onAlertAction | EventEmitter<MouseEvent> | - | Emitted when action button is clicked |

AlertTitleComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | class | string | '' | Additional CSS classes |

AlertContentComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | class | string | '' | Additional CSS classes |

AlertIconComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | class | string | '' | Additional CSS classes |

AlertActionComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | class | string | '' | Additional CSS classes | | onClick | EventEmitter<MouseEvent> | - | Emitted when action button is clicked |

Accessibility

• Keyboard Navigation: Full support for Tab, Shift+Tab, Enter, Space, and Arrow keys
• ARIA Attributes: Proper ARIA labels, roles, and states
• Focus Management: Visible focus indicators and proper focus handling
• Screen Reader: Compatible with screen readers
• Semantic Structure: Uses proper HTML semantic elements

ARIA Features

• role="alert" on alert containers
• aria-live regions for screen reader announcements
• aria-atomic for complete message reading
• aria-label and aria-describedby for enhanced accessibility
• Keyboard accessible dismiss button with proper focus management

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

See the main project CONTRIBUTING.md for guidelines.

Part of ng-shangjc component library • Documentation