# Button

## Overview

The primary interaction trigger. Use `Button` for any user-initiated action: form submission, navigation triggers, dialog openers, and destructive confirmations. It supports multiple visual variants, sizes, icon-only mode, and the `asChild` pattern for composing with router links.

---

## When to Use

- Submitting forms (primary action)
- Opening dialogs, drawers, or sheets
- Triggering secondary or ghost actions (cancel, go back)
- Icon-only controls in toolbars and headers

## When NOT to Use

- **URL navigation without action intent** — use `<Button asChild><Link to="...">` or a navigation component instead of a plain `<Button>`.
- **Destructive actions without confirmation** — always pair with an `<AlertDialog>` before executing irreversible actions.
- **Never use native `<button>` HTML element** — always use `<Button>` from `xertica-ui`.

---

## Variants

| Variant       | Visual                         | Usage                            |
| ------------- | ------------------------------ | -------------------------------- |
| `default`     | Filled primary color           | Main CTA, form submit            |
| `secondary`   | Filled muted color             | Secondary action                 |
| `outline`     | Border, transparent background | Alternative secondary            |
| `ghost`       | Transparent, hover accent      | Subtle controls, toolbar buttons |
| `destructive` | Filled red/danger color        | Irreversible danger actions      |
| `link`        | Text-only, underlined          | Inline text links                |
| `success`     | Filled green                   | Positive confirmation actions    |
| `info`        | Filled blue                    | Informational triggers           |
| `warning`     | Filled amber                   | Cautionary actions               |

---

## Sizes

| Size      | Height    | Usage                        |
| --------- | --------- | ---------------------------- |
| `default` | `h-9`     | Standard                     |
| `sm`      | `h-8`     | Compact areas, table rows    |
| `lg`      | `h-10`    | Hero CTAs, prominent actions |
| `icon`    | `h-9 w-9` | Icon-only buttons            |

---

## Props

| Prop        | Type                                                                                                              | Default     | Required | Description                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------------------------------------------------- |
| `variant`   | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link' \| 'success' \| 'info' \| 'warning'` | `'default'` | No       | Visual style                                               |
| `size`      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                                                             | `'default'` | No       | Size preset                                                |
| `loading`   | `boolean`                                                                                                         | `false`     | No       | Disables and shows a spinner while preserving button width |
| `disabled`  | `boolean`                                                                                                         | `false`     | No       | Disables interaction                                       |
| `asChild`   | `boolean`                                                                                                         | `false`     | No       | Renders as the child component (for Link composition)      |
| `className` | `string`                                                                                                          | —           | No       | Additional CSS classes                                     |
| `onClick`   | `() => void`                                                                                                      | —           | No       | Click handler                                              |
| `type`      | `'button' \| 'submit' \| 'reset'`                                                                                 | `'button'`  | No       | HTML button type                                           |

All other native `button` HTML attributes are forwarded.

---

## Examples

### Standard Variants

```tsx
import { Button } from 'xertica-ui/ui';

<Button variant="default">Save</Button>
<Button variant="secondary">Cancel</Button>
<Button variant="outline">Export</Button>
<Button variant="ghost">Learn More</Button>
<Button variant="destructive">Delete Account</Button>
<Button variant="success">Confirm</Button>
<Button variant="info">Details</Button>
<Button variant="warning">Review</Button>
```

### With Icon

```tsx
import { Plus, Trash2 } from 'lucide-react';

<Button>
  <Plus className="size-4" />
  New Member
</Button>

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

### Icon Only

```tsx
import { Settings } from 'lucide-react';

<Button variant="ghost" size="icon" aria-label="Open settings">
  <Settings className="size-4" />
</Button>;
```

### Composed with Router Link

```tsx
import { Link } from 'react-router-dom';

<Button asChild>
  <Link to="/dashboard">Go to Dashboard</Link>
</Button>;
```

### Action Pair

```tsx
<div className="flex justify-end gap-2">
  <Button variant="ghost">Cancel</Button>
  <Button type="submit">Save Changes</Button>
</div>
```

---

## Accessibility

- Has visible focus ring (`ring-ring`) via keyboard navigation.
- Use `aria-label` for icon-only buttons to provide screen reader context.
- When `disabled`, the button is non-interactive and visually muted.

---

## AI Rules

- **Never use `<button>`** — always use `<Button>` from `xertica-ui`.
- **Never invent new variants** — use only the 9 documented variants.
- **Never place two `variant="default"` buttons side by side** — one should be `ghost`, `outline`, or `secondary`.
- For form submission, always set `type="submit"` on the submit button.
- `size="icon"` requires the button to contain only a single icon element — adding text breaks the square aspect ratio.
- When the button triggers a destructive action, use `variant="destructive"` and always confirm with `<AlertDialog>` first.

---

## Related Components

- [`AlertDialog`](./alert-dialog.md) — Required before destructive button actions
- [`Dialog`](./dialog.md) — Common button target
- [`Form`](./form.md) — Submit button context
- [`DropdownMenu`](./dropdown-menu.md) — Often paired with ghost icon buttons