Button Component

A versatile and highly customizable button component with multiple variants, sizes, and states. Built with Angular signals and TailwindCSS for modern, reactive UI development. Perfect for any application needing reliable, accessible button interactions.

Official Documentation

Features

• 🚀 Multiple Variants: 6 visual styles (default, destructive, outline, secondary, ghost, link) for any design context
• 🎨 Flexible Sizing: 4 size options (sm, default, lg, icon) to match your layout needs
• ⚡ Signal-based State: Modern Angular signals for reactive, performant updates
• ♿ Accessibility: Full ARIA support, keyboard navigation, and screen reader compatibility
• ⌨️ Keyboard Navigation: Complete support for Tab, Enter, Space, and Escape keys
• 🎯 Type-Safe: Full TypeScript support with proper interfaces and type checking
• 🎨 Customizable: Easy theming with CSS variables and custom class support
• 🔧 Composition: Use asChild prop to compose with other elements while maintaining button behavior
• 📱 Responsive: Adapts seamlessly to different screen sizes and devices
• ⚡ Performance: Optimized with OnPush change detection and efficient rendering

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

ng-shangjc install button

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 button component directly in your standalone components:

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    ButtonComponent
  ],
  template: `
    <ng-shangjc-button 
      variant="default" 
      size="default"
      (click)="handleClick()">
      Click me
    </ng-shangjc-button>
  `
})
export class ExampleComponent {
  handleClick() {
    console.log('Button clicked!');
  }
}

Using NgModule (Legacy)

If you're using NgModules, import the ButtonModule:

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

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

Then use the button in your templates:

<ng-shangjc-button variant="secondary" size="lg">Click me</ng-shangjc-button>

Basic Usage

Default Example

import { Component } from '@angular/core';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <ng-shangjc-button>Click me</ng-shangjc-button>
  `,
})
export class ExampleComponent {}

Alternative Usage Patterns

With Variants

<ng-shangjc-button variant="default">Default</ng-shangjc-button>
<ng-shangjc-button variant="secondary">Secondary</ng-shangjc-button>
<ng-shangjc-button variant="destructive">Destructive</ng-shangjc-button>
<ng-shangjc-button variant="outline">Outline</ng-shangjc-button>
<ng-shangjc-button variant="ghost">Ghost</ng-shangjc-button>
<ng-shangjc-button variant="link">Link</ng-shangjc-button>

With Sizes

<ng-shangjc-button size="sm">Small</ng-shangjc-button>
<ng-shangjc-button size="default">Default</ng-shangjc-button>
<ng-shangjc-button size="lg">Large</ng-shangjc-button>
<ng-shangjc-button size="icon">
  <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6v6m0 0v6m0-6h6m-6 0H6"/>
  </svg>
</ng-shangjc-button>

Advanced Usage

Composing with asChild

The asChild prop allows you to compose the button with other elements while maintaining button styling and behavior:

import { Component } from '@angular/core';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-as-child-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <!-- As a link -->
    <ng-shangjc-button variant="outline" [asChild]="true">
      <a href="/dashboard" class="no-underline">
        Go to Dashboard
      </a>
    </ng-shangjc-button>

    <!-- With custom element -->
    <ng-shangjc-button [asChild]="true" (click)="handleCustomClick()">
      <div class="flex items-center gap-2 cursor-pointer">
        <svg class="h-4 w-4">...</svg>
        <span>Custom Element</span>
      </div>
    </ng-shangjc-button>
  `
})
export class AsChildExampleComponent {
  handleCustomClick() {
    console.log('Custom element clicked!');
  }
}

Loading States

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

@Component({
  selector: 'app-loading-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <ng-shangjc-button [disabled]="isLoading()" (click)="submit()">
      @if (isLoading()) {
        <svg class="mr-2 h-4 w-4 animate-spin" fill="none" viewBox="0 0 24 24">
          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
        </svg>
        Loading...
      } @else {
        Submit
      }
    </ng-shangjc-button>
  `
})
export class LoadingExampleComponent {
  isLoading = signal(false);

  async submit() {
    this.isLoading.set(true);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 2000));
    this.isLoading.set(false);
  }
}

API Reference

ButtonComponent

| Property | Type | Default | Description | |----------|------|---------|-------------| | variant | 'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link' | 'default' | The visual style variant of the button | | size | 'default' \| 'sm' \| 'lg' \| 'icon' | 'default' | The size of the button | | type | 'button' \| 'submit' \| 'reset' | 'button' | The HTML button type | | disabled | boolean | false | Whether the button is disabled | | asChild | boolean | false | Whether to render as child element (composition) | | class | string | '' | Additional CSS classes to apply |

Events

| Event | Type | Description | |-------|------|-------------| | click | EventEmitter<Event> | Emitted when button is clicked (standard DOM click event) |

Accessibility

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

ARIA Features

• role="button" (implicit on button element)
• tabindex="0" (implicit for keyboard navigation)
• aria-disabled="true" when disabled state is active
• aria-expanded support for toggle button patterns
• Focus-visible styles for keyboard navigation
• High contrast mode support
• Screen reader announcements for state changes

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