# Button Component Documentation

## Overview

The Button component is a fundamental UI element used to trigger actions or events. It supports multiple visual styles, sizes, and states for different use cases like form submission, dialog opening, action cancellation, and delete operations.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'destructive' \| 'ghost' \| 'link'` | `'primary'` | Visual appearance style |
| `size` | `'sm' \| 'base' \| 'lg'` | `'base'` | Button dimensions |
| `icon` | `boolean` | `false` | Optimizes spacing for icon-only buttons |
| `asChild` | `boolean` | `false` | Uses Slot to render as child component |
| ...button props | `ComponentProps<'button'>` | — | All standard HTML button attributes supported |

## Variants

### Primary
The default style for main actions:
```jsx
<Button>Primary</Button>
<Button>Primary Action</Button>
<Button icon aria-label="Primary action">
  <Plus className="size-4" />
</Button>
```

### Secondary
Alternative action style:
```jsx
<Button variant="secondary">Secondary</Button>
<Button variant="secondary">
  <Plus className="size-4 mr-2" />
  Add Item
</Button>
```

### Destructive
For dangerous operations like deletion:
```jsx
<Button variant="destructive">Destructive</Button>
<Button variant="destructive">
  <Trash className="size-4 mr-2" />
  Delete
</Button>
```

### Ghost
Subtle action style:
```jsx
<Button variant="ghost">Ghost</Button>
<Button variant="ghost" icon>
  <Settings className="size-4" />
</Button>
```

## Sizes

### Small
```jsx
<Button size="sm">Small</Button>
<Button size="sm" variant="secondary">
  <Plus className="size-3 mr-1" />
  Add
</Button>
```

### Default
```jsx
<Button>Default</Button>
<Button>
  <Save className="size-4 mr-2" />
  Save Changes
</Button>
```

### Large
```jsx
<Button size="lg">Large</Button>
<Button size="lg" className="px-8">
  <ArrowRight className="size-5 mr-2" />
  Get Started
</Button>
```

## Icon Buttons

Use the `icon` prop to properly space icon-only buttons across different sizes and variants:

```jsx
<Button icon size="sm" aria-label="Settings">
  <Settings className="size-3" />
</Button>

<Button icon variant="secondary" aria-label="Edit">
  <Edit className="size-4" />
</Button>

<Button icon variant="destructive" aria-label="Delete">
  <Trash2 className="size-4" />
</Button>
```

## States

### Disabled
```jsx
<Button disabled>Disabled</Button>
<Button disabled title="Complete required fields first">
  <Lock className="size-4 mr-2" />
  Submit Form
</Button>
```

## Type Definition

```typescript
interface ButtonProps extends ComponentProps<"button">, VariantProps<typeof buttonVariants> {
  asChild?: boolean;
  variant?: "primary" | "secondary" | "destructive" | "ghost" | "link";
  size?: "sm" | "md" | "lg";
  icon?: boolean;
}
```

## Usage Example

```jsx
import { Button } from '@vuer-ai/vuer-uikit';

function MyComponent() {
  return (
    <div>
      <Button>Primary Button</Button>
      <Button variant="secondary">Secondary Button</Button>
      <Button variant="destructive">Destructive Button</Button>
      <Button size="sm">Small Button</Button>
      <Button size="lg">Large Button</Button>
      <Button disabled>Disabled Button</Button>
    </div>
  );
}
```