Badge Component

A flexible badge component for status indicators, labels, and notifications with multiple variants, sizes, and icon support. Perfect for displaying status information, notification counts, and categorical tags with built-in accessibility and dismissible functionality.

Official Documentation

Features

• 🎨 Multiple Variants: Default, secondary, destructive, outline, success, warning, and info styles
• 📏 Size Options: Small, default, and large variants with responsive sizing
• 🔧 Icon Support: Leading and trailing icon slots with automatic sizing
• ❌ Dismissible: Optional close button functionality with fade animation support
• ♿ Accessibility: Proper ARIA attributes, keyboard navigation, and screen reader support
• ⌨️ Keyboard Navigation: Full keyboard accessibility for interactive elements
• 🎯 Type-Safe: Complete TypeScript support with typed variants and properties
• � Customizable: Additional CSS classes and styling options
• ⚡ Performance: Optimized with OnPush change detection and computed properties

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 badge component into your project:

ng-shangjc install badge

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 { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    BadgeComponent,
  ],
  template: `
    <ng-shangjc-badge>
      Badge content
    </ng-shangjc-badge>
  `
})
export class ExampleComponent { }

Using NgModule (Legacy)

If you're using NgModules, import the BadgeModule:

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

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

Then use the components in your templates:

<ng-shangjc-badge>
  Badge content
</ng-shangjc-badge>

Basic Usage

Default Example

import { Component } from '@angular/core';
import { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <ng-shangjc-badge>New</ng-shangjc-badge>
    <ng-shangjc-badge variant="secondary">Updated</ng-shangjc-badge>
    <ng-shangjc-badge variant="destructive">Error</ng-shangjc-badge>
  `,
})
export class ExampleComponent {}

Alternative Usage Patterns

Status Indicators

<ng-shangjc-badge variant="success">Active</ng-shangjc-badge>
<ng-shangjc-badge variant="warning">Pending</ng-shangjc-badge>
<ng-shangjc-badge variant="destructive">Blocked</ng-shangjc-badge>

Notification Badges

<div class="relative">
  <button>Messages</button>
  <ng-shangjc-badge 
    variant="destructive" 
    size="sm" 
    [dismissible]="true"
    (dismissed)="clearNotification()"
    class="absolute -top-2 -right-2">
    5
  </ng-shangjc-badge>
</div>

Advanced Usage

Dismissible Badge

import { Component } from '@angular/core';
import { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-dismissible-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <!-- Basic dismissible badge -->
    <ng-shangjc-badge 
      [dismissible]="true"
      (dismissed)="onBadgeDismiss()">
      Dismissible badge
    </ng-shangjc-badge>

    <!-- With fade animation on dismiss -->
    <ng-shangjc-badge
      [dismissible]="true"
      [fade]="true"
      (dismissed)="onBadgeDismiss()">
      Fade out on dismiss
    </ng-shangjc-badge>
  `
})
export class DismissibleExampleComponent {
  onBadgeDismiss() {
    console.log('Badge dismissed');
  }
}

Badge with Icons

@Component({
  selector: 'app-icon-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <!-- Leading icon -->
    <ng-shangjc-badge>
      <svg leadingIcon class="h-3 w-3" 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>
      Verified
    </ng-shangjc-badge>

    <!-- Trailing icon -->
    <ng-shangjc-badge>
      Online
      <div trailingIcon class="h-2 w-2 bg-green-400 rounded-full"></div>
    </ng-shangjc-badge>
  `
})
export class IconExampleComponent {}

Custom Styling

@Component({
  selector: 'app-custom-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <ng-shangjc-badge 
      class="bg-purple-500 text-white hover:bg-purple-600">
      Custom
    </ng-shangjc-badge>
  `
})
export class CustomExampleComponent {}

API Reference

BadgeComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | variant | 'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info' | 'default' | Badge style variant | | size | 'sm' \| 'default' \| 'lg' | 'default' | Badge size | | dismissible | boolean | false | When true, shows a close button that removes the badge from the DOM when clicked | | fade | boolean | false | Whether to use fade animation when dismissing (only applies when dismissible is true) | | class | string | '' | Additional CSS classes | | role | string | 'status' | ARIA role attribute | | ariaLabel | string | undefined | ARIA label for accessibility | | dismissed | EventEmitter<void> | - | Emitted when a dismissible badge is closed |

Accessibility

• Keyboard Navigation: Full support for Tab, Shift+Tab, Enter, and Space keys on dismiss button
• ARIA Attributes: Proper ARIA labels, roles, and states for screen readers
• Focus Management: Visible focus indicators and proper focus handling on interactive elements
• Screen Reader: Compatible with screen readers and properly announces badge content and dismiss actions
• Semantic Structure: Uses proper HTML semantic elements with appropriate role attributes

ARIA Features

• role="status" by default for non-interactive badges
• aria-label support for custom badge descriptions
• aria-label on dismiss button with context-aware text
• Focus management for dismissible badges
• Screen reader announcements for dismiss actions

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