angular-superui

v2.0.3

Published

9 months ago

A modern Angular UI component library with 43+ components and 15 UI blocks, built with Tailwind CSS

0High
0Medium
0Low

kajukatli

angular ui components tailwind typescript

Angular SuperUI v2.0.3 🚀

🌟 🚀 LIVE DEMO - Interactive Component Showcase! 🌟

✨ All 43 Components + 15 Blocks • Dark Mode • Mobile Responsive • TypeScript Ready ✨

🌟 Key Features in v2.0.3

43 Essential Components + 15 UI Blocks - Production-ready UI components and blocks
**Zero ####1. 🔘 Button17. 19. 📄24. 🖱️ ContextMenu36. 📁 FileUpload - Advanced file upload component with drag-and-drop, progress tracking, and validation - Right-click context menus with keyboard shortcutsPagination - Pagination controls with customizable page size and navigation📄 Textarea - Multi-line text input component with auto-resize and validation states- Interactive buttons with 9 variants and loading states 🚀 Core UI Components 🎯 Core UI Com17. 19. 📄24. 🖱️ ContextMenu36. 📁 FileUpload - Advanced file upload component with drag-and-drop, progress tracking, and validation - Right-click context menus with keyboard shortcutsPagination - Pagination controls with customizable page size and navigation📄 Textarea - Multi-line text input component with auto-resize and validation statesonents

🔘 Button - Interactive buttons with 9 variants and loading statesernal Dependencies** - Local-first architecture for maximum control

A modern, beautiful, and accessible Angular UI component library built with Tailwind CSS and TypeScript. Angular SuperUI provides a comprehensive set of 39 essential UI components + 5 UI blocks with multiple variants, CLI-based installation, and TypeScript-first development.

🚀 📖 Complete Documentation →

🚀 Step-by-step guides for all 43 components + 10 blocks with practical examples, usage instructions, and styling tips!

🛠️ v2.0.3: 43 Components + 15 Blocks Ready

🚀 CLI Tool (Recommended)

Install components directly in your project with our enhanced CLI:

# Install CLI globally
npm install -g ngsui-cli

# Initialize project (sets up Tailwind CSS and TypeScript configs)
ngsui-cli init

# Add specific components
ngsui-cli add button card badge alert checkbox theme-switcher

# List all available components
ngsui-cli list

📦 NPM Package Installation

Install the complete component library:

```bash
ng add [email protected]
# or
npm install [email protected]


### 🌟 **Key Features in v2.0.3**

- **39 Essential Components + 5 UI Blocks** - Production-ready UI components and blocks
- **Enhanced Block System** - New Hero Section, Feature Grid, Pricing Cards, Header, and Footer blocks
- **TypeScript First** - Full type safety and IntelliSense support
- **Tailwind CSS Integration** - Utility-first styling approach
- **Angular 18+ Support** - Built for modern Angular applications

## 📦 **All 43 Components + 10 Blocks Available**

### 🎯 Core Components

- **Button** - Interactive buttons with multiple variants and loading states
- **Badge** - Status indicators and labels with color variants
- **Alert** - Display important messages and notifications
- **Aspect Ratio** - Responsive aspect ratio containers for media content
- **Card** - Flexible content containers with header, body, and footer
- **Checkbox** - Toggle controls with full accessibility support
- **Input** - Accessible and customizable input fields with validation
- **Radio Group** - Radio button groups with form integration
- **Select** - Dropdown selection with search and multi-select capabilities

### 🧭 Navigation Components

- **Breadcrumb** - Navigation hierarchy with custom separators
- **Dropdown Menu** - Contextual menu dropdowns with keyboard navigation
- **Pagination** - Navigate through large datasets with intelligent controls
- **Drawer** - Slide-out panels from screen edges
- **Sidebar** - Responsive navigation sidebar with animations and keyboard support
- **Stepper** - Multi-step navigation with progress tracking and validation

### 🖼️ Display Components

- **Avatar** - User profile pictures with fallback support
- **Carousel** - Image and content sliders with auto-play
- **Data Table** - Feature-rich table for displaying large datasets
- **Progress** - Progress indicators with accessibility
- **Skeleton** - Loading placeholders with smooth animations

### 💫 Overlay Components

- **Alert Dialog** - Modal dialogs with focus management
- **Context Menu** - Right-click context menus with accessibility
- **Dialog** - Modal windows and overlays
- **Popover** - Floating content containers with smart positioning

### 🔧 Form Components

- **Calendar** - Date picker with full keyboard navigation
- **Collapsible** - Expandable content sections with animations
- **Combobox** - Advanced dropdown with search and multi-select
- **Input OTP** - Secure one-time password input with validation
- **Slider** - Range input controls with precise value selection

### ⚙️ Utility Components

- **Accordion** - Vertically stacked interactive sections
- **Theme Switcher** - Dark/light mode toggle with smooth transitions

## 📚 **Quick Links**

- 📚 **[Component Examples →](../../docs/examples.md)** - Real-world usage examples
- 📖 **[Installation Guide →](../../docs/installation.md)** - Detailed setup instructions  
- 🔧 **[GitHub Repository →](https://github.com/bhaimicrosoft/angular-superui)** - Source code and issues

## ✨ Features

- 🛠️ **CLI Tool** - Selective component installation with ngsui
- 🎨 **31 Essential Components** - Production-ready UI component library  
- 🌈 **Multiple Variants** - Customizable styling options for all components
- 🔧 **TypeScript First** - Full type safety and excellent IntelliSense support
- ♿ **Accessible** - Built with accessibility in mind (ARIA compliant)
- 🎯 **Tree Shakable** - Import only what you need
- 🚀 **Angular 18+** - Built for modern Angular features and standalone components
- 📱 **Responsive** - Mobile-first design approach
- 📦 **Tailwind CSS** - Utility-first CSS framework integration
- 🔄 **Form Integration** - Full Angular Forms support with ControlValueAccessor

## 📦 Installation

### Option 1: CLI Tool - Selective Installation (Recommended)

Perfect for new projects or when you want to reduce bundle size:

```bash
# Install CLI globally
npm install -g ngsui-cli

# Initialize your Angular project
ngsui-cli init

# Add specific components
ngsui-cli add button card badge alert checkbox

# List all available components
ngsui-cli list

Option 2: Full Library Installation

Install the complete library:

# Using Angular CLI (recommended)
ng add angular-superui

# Or using npm
npm install angular-superui

Using npm

npm install angular-superui

Manual Setup

Install the package and peer dependencies:

npm install angular-superui class-variance-authority clsx tailwind-merge

Configure your styles.css for Tailwind CSS v4:

@import "tailwindcss";

@layer base {
  :root {
    --border: hsl(214.3 31.8% 91.4%);
    --input: hsl(214.3 31.8% 91.4%);
    --ring: hsl(222.2 84% 4.9%);
    --background: hsl(0 0% 100%);
    --foreground: hsl(222.2 84% 4.9%);
    --primary: hsl(222.2 47.4% 11.2%);
    --primary-foreground: hsl(210 40% 98%);
    --secondary: hsl(210 40% 96.1%);
    --secondary-foreground: hsl(222.2 47.4% 11.2%);
    --destructive: hsl(0 84.2% 60.2%);
    --destructive-foreground: hsl(210 40% 98%);
    --muted: hsl(210 40% 96.1%);
    --muted-foreground: hsl(215.4 16.3% 46.9%);
    --accent: hsl(210 40% 96.1%);
    --accent-foreground: hsl(222.2 47.4% 11.2%);
    --card: hsl(0 0% 100%);
    --card-foreground: hsl(222.2 84% 4.9%);
    --popover: hsl(0 0% 100%);
    --popover-foreground: hsl(222.2 84% 4.9%);
    --radius: 0.5rem;
  }

  .dark {
    --border: hsl(217.2 32.6% 17.5%);
    --input: hsl(217.2 32.6% 17.5%);
    --ring: hsl(212.7 26.8% 83.9%);
    --background: hsl(222.2 84% 4.9%);
    --foreground: hsl(210 40% 98%);
    --primary: hsl(210 40% 98%);
    --primary-foreground: hsl(222.2 47.4% 11.2%);
    --secondary: hsl(217.2 32.6% 17.5%);
    --secondary-foreground: hsl(210 40% 98%);
    --destructive: hsl(0 62.8% 30.6%);
    --destructive-foreground: hsl(210 40% 98%);
    --muted: hsl(217.2 32.6% 17.5%);
    --muted-foreground: hsl(215 20.2% 65.1%);
    --accent: hsl(217.2 32.6% 17.5%);
    --accent-foreground: hsl(210 40% 98%);
    --card: hsl(222.2 84% 4.9%);
    --card-foreground: hsl(210 40% 98%);
    --popover: hsl(222.2 84% 4.9%);
    --popover-foreground: hsl(210 40% 98%);
  }

  body {
    background-color: hsl(var(--background));
    color: hsl(var(--foreground));
  }
}

Import components in your Angular app:

import { Component } from '@angular/core';
import { 
  Button, 
  Avatar, 
  Alert, 
  Badge, 
  Card, 
  CardHeader, 
  CardTitle, 
  CardContent,
  Checkbox,
  ThemeSwitcher 
} from 'angular-superui';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    Button, 
    Avatar, 
    Alert, 
    Badge, 
    Card, 
    CardHeader, 
    CardTitle, 
    CardContent,
    Checkbox,
    ThemeSwitcher
  ],
  template: `
    <div class="p-6 space-y-6">
      <!-- Theme Switcher -->
      <lib-theme-switcher></lib-theme-switcher>
      
      <!-- Welcome Card -->
      <Card class="w-96">
        <CardHeader>
          <CardTitle>Welcome to Angular SuperUI</CardTitle>
        </CardHeader>
        <CardContent>
          <!-- Avatar Component -->
          <Avatar 
            size="lg" 
            [src]="'https://github.com/shadcn.png'"
            [alt]="'User Avatar'"
            class="mb-4">
          </Avatar>

          <!-- Alert Component -->
          <Alert variant="default" class="mb-4">
            <h4 class="font-medium">Success!</h4>
            <p class="text-sm">Your component library is ready to use.</p>
          </Alert>

          <!-- Button Components -->
          <div class="flex gap-2 mb-4">
            <Button variant="default">Default</Button>
            <Button variant="secondary">Secondary</Button>
            <Button variant="outline">Outline</Button>
          </div>

          <!-- Badge Components -->
          <div class="flex gap-2 mb-4">
            <Badge variant="default">Default</Badge>
            <Badge variant="secondary">Secondary</Badge>
            <Badge variant="destructive">Important</Badge>
          </div>

          <!-- Checkbox Components -->
          <div class="flex flex-col gap-2">
            <div class="flex items-center space-x-2">
              <Checkbox [(ngModel)]="isChecked" />
              <label class="text-sm">Accept terms and conditions</label>
            </div>
            <div class="flex items-center space-x-2">
              <Checkbox variant="success" [(ngModel)]="isSubscribed" />
              <label class="text-sm">Subscribe to newsletter</label>
            </div>
          </div>
        </CardContent>
      </Card>
    </div>
  `
})
export class ExampleComponent {
  // Component logic here
  isChecked = false;
  isSubscribed = false;
}

🎨 Component Variants

Theme Switcher

A dark/light theme switcher with system preference detection:

<ThemeSwitcher />

Button Variants

Each button component supports multiple styling options:

// Basic variants
<Button variant="default">Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon</Button>

Badge Variants

Status and labeling options:

<Badge variant="default">Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Important</Badge>
<Badge variant="outline">Outline</Badge>

Alert Variants

Contextual feedback styling:

<Alert variant="default">Default message</Alert>
<Alert variant="destructive">Error message</Alert>

Checkbox Variants

Boolean input controls with multiple states:

<Checkbox [(ngModel)]="isChecked">Default checkbox</Checkbox>
<Checkbox variant="success" [(ngModel)]="isSuccess">Success checkbox</Checkbox>
<Checkbox variant="warning" [(ngModel)]="isWarning">Warning checkbox</Checkbox>
<Checkbox variant="destructive" [(ngModel)]="isError">Error checkbox</Checkbox>

<!-- Different sizes -->
<Checkbox size="sm" [(ngModel)]="isSmall">Small checkbox</Checkbox>
<Checkbox size="default" [(ngModel)]="isDefault">Default checkbox</Checkbox>
<Checkbox size="lg" [(ngModel)]="isLarge">Large checkbox</Checkbox>
<Checkbox size="xl" [(ngModel)]="isXLarge">Extra large checkbox</Checkbox>

<!-- Different states -->
<Checkbox [(ngModel)]="isChecked">Checked state</Checkbox>
<Checkbox [indeterminate]="true">Indeterminate state</Checkbox>
<Checkbox [disabled]="true" [(ngModel)]="isDisabled">Disabled state</Checkbox>

🧩 Available Components (39)

� Core UI Components

� Button - Interactive buttons with 9 variants and loading states
🏷️ Badge - Status indicators and labels with 4 variants
🚨 Alert - Contextual feedback messages with 5 variants
👤 Avatar - User profile images with automatic fallback support
🪗 Accordion - Collapsible content sections with single or multiple modes
📐 AspectRatio - Maintains consistent proportions for responsive content
🃏 Card - Flexible content containers with header, content, and footer
☑️ Checkbox - Boolean input control with multiple states and form integration
🔽 ComboBox - Advanced dropdown with search, multi-select, and loading states
📝 Input - Flexible input component with validation states and accessibility
🔢 InputOTP - One-time password input with multiple slots and validation
🔘 RadioGroup - Radio button group with accessible selection and validation
📊 Progress - Progress indicator with customizable appearance and animation
⭐ Rating - Interactive star rating component with hover effects and customizable appearance
🔽 Select - A flexible select dropdown component with search and multi-select capabilities
🎚️ Slider - Interactive slider component for single values and ranges with accessibility support
� Textarea - Multi-line text input component with auto-resize and validation states

🧭 Navigation & Layout Components

🍞 Breadcrumb - Navigation breadcrumbs with accessibility and custom separators
� Pagination - Pagination controls with customizable page size and navigation
🏠 Sidebar - Responsive navigation sidebar with animations, keyboard navigation, and flexible content
📋 Stepper - Multi-step navigation component with progress tracking and validation support
📑 Tabs - Tabbed interface component with keyboard navigation and accessibility support

💫 Overlay & Dialog Components

🚨 AlertDialog - Modal dialogs with accessibility and focus management
�️ ContextMenu - Right-click context menus with keyboard shortcuts
🪟 Dialog - Modal dialog windows with accessibility features
📄 Drawer - Flexible drawer component that slides in from any side
⬇️ DropdownMenu - Beautiful dropdown menus with multiple variants
💬 Popover - Floating overlay that displays content relative to a trigger
📢 Toast - Toast notification component with multiple variants and auto-dismiss functionality
💡 Tooltip - Tooltip component with configurable positioning and hover/focus triggers

🎨 Media & Display Components

🎠 Carousel - Content slider with auto-play, navigation, and pagination
🗃️ Collapsible - Expandable content sections with smooth animations
💀 Skeleton - Loading placeholder components with customizable shapes and animations
⏳ Spinner - Loading spinner component with multiple variants and animations

📊 Data & Tables

📊 DataTable - Enterprise-grade data table with sorting, filtering, and pagination

📁 File Management

� FileUpload - Advanced file upload component with drag-and-drop, progress tracking, and validation

📅 Featured Components

📅 Calendar - Advanced calendar with date range selection and time picker

⚙️ Utility Components

🌓 ThemeSwitcher - Toggle between light, dark, and system themes
🗃️ Collapsible - Expandable content sections with smooth animations and keyboard support

🖼️ Enhanced Avatar Component

The Avatar component now supports full image functionality:

// Image source with automatic fallback
<Avatar 
  size="lg" 
  [src]="'https://github.com/shadcn.png'"
  [alt]="'User Avatar'">
</Avatar>

// Custom fallback text
<Avatar [fallback]="'JD'"></Avatar>

// Auto-generated initials from alt text
<Avatar [alt]="'John Doe'"></Avatar>

// Multiple sizes
<Avatar size="sm"></Avatar>    <!-- 32px -->
<Avatar size="default"></Avatar> <!-- 40px -->
<Avatar size="lg"></Avatar>    <!-- 48px -->
<Avatar size="xl"></Avatar>    <!-- 64px -->

Features:

src property for image URLs
alt property for accessibility and initials generation
fallback property for custom fallback text
Automatic error handling for failed image loads
Intelligent initials generation from names
Modern Angular 18+ control flow syntax

📚 Advanced Examples

Simple Dashboard Layout

@Component({
  template: `
    <div class="p-6 space-y-6">
      <!-- Header with Avatar -->
      <div class="flex items-center justify-between">
        <h1 class="text-2xl font-bold">Dashboard</h1>
        <Avatar 
          size="default" 
          [src]="'https://github.com/shadcn.png'"
          [alt]="'User Avatar'">
        </Avatar>
      </div>

      <!-- Alert Notification -->
      <Alert variant="default">
        <h4 class="font-medium">Welcome back!</h4>
        <p class="text-sm">You have 3 new notifications.</p>
      </Alert>

      <!-- Action Buttons -->
      <div class="flex gap-2">
        <Button variant="default">Create</Button>
        <Button variant="secondary">Save Draft</Button>
        <Button variant="destructive">Delete</Button>
      </div>

      <!-- Status Cards -->
      <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
        <Card>
          <CardHeader>
            <CardTitle>Sales</CardTitle>
          </CardHeader>
          <CardContent>
            <div class="text-2xl font-bold">$12,345</div>
            <Badge variant="default" class="mt-2">+12%</Badge>
          </CardContent>
        </Card>
        
        <Card>
          <CardHeader>
            <CardTitle>Orders</CardTitle>
          </CardHeader>
          <CardContent>
            <div class="text-2xl font-bold">1,234</div>
            <Badge variant="secondary" class="mt-2">+8%</Badge>
          </CardContent>
        </Card>
        
        <Card>
          <CardHeader>
            <CardTitle>Users</CardTitle>
          </CardHeader>
          <CardContent>
            <div class="text-2xl font-bold">5,678</div>
            <Badge variant="destructive" class="mt-2">-3%</Badge>
          </CardContent>
        </Card>
      </div>
    </div>
  `
})
export class DashboardComponent {
  // Component logic here
}

🔧 TypeScript Support

Full TypeScript support with intelligent IntelliSense:

import type { ButtonVariant, AvatarSize } from 'angular-superui';

// Type-safe component usage
const buttonVariant: ButtonVariant = 'default';
const avatarSize: AvatarSize = 'lg';

// All components are fully typed
<Button [variant]="buttonVariant">Typed Button</Button>
<Avatar [size]="avatarSize">Typed Avatar</Avatar>

♿ Accessibility

Angular SuperUI components are built with accessibility in mind:

ARIA Attributes: Proper ARIA attributes and roles for screen readers
Keyboard Navigation: Full keyboard accessibility support
Semantic HTML: Uses appropriate HTML elements for better accessibility
Focus Management: Visible focus indicators and logical focus flow
High Contrast: Components work well in high contrast mode

🌙 Dark Mode

Components automatically adapt to your theme preferences:

/* Dark mode support through CSS variables */
.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  /* Components automatically use these variables */
}

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📧 Support

📦 npm: angular-superui
🐙 GitHub: bhaimicrosoft/angular-superui
📧 Email: [email protected]

Built with ❤️ by the Angular SuperUI Team