> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Button

> Interactive button with multiple variants, custom colors, and action handling

# Button

The Button component provides an interactive element with various visual styles, custom color support, and action handling.

## Props

| Prop            | Type               | Default     | Description                                                         |
| --------------- | ------------------ | ----------- | ------------------------------------------------------------------- |
| `label`         | `string`           | -           | Button text                                                         |
| `variant`       | `string`           | `"primary"` | Style variant: `primary`, `secondary`, `outline`, `ghost`, `danger` |
| `size`          | `string`           | `"md"`      | Button size: `sm`, `md`, `lg`, `xl`                                 |
| `color`         | `string`           | -           | Custom background color (overrides variant)                         |
| `textColor`     | `string`           | -           | Custom text color                                                   |
| `borderColor`   | `string`           | -           | Custom border color                                                 |
| `borderWidth`   | `number`           | -           | Custom border width                                                 |
| `radius`        | `string \| number` | -           | Border radius: `none`, `sm`, `md`, `lg`, `xl`, `full`, or number    |
| `shadow`        | `string`           | `"none"`    | Shadow depth: `none`, `sm`, `md`, `lg`                              |
| `icon`          | `string`           | -           | Icon name on the left                                               |
| `iconStart`     | `string`           | -           | Icon name on the left (alias)                                       |
| `iconEnd`       | `string`           | -           | Icon name on the right                                              |
| `iconRight`     | `string`           | -           | Icon name on the right (alias)                                      |
| `disabled`      | `boolean`          | `false`     | Disabled state                                                      |
| `loading`       | `boolean`          | `false`     | Loading state with spinner                                          |
| `fullWidth`     | `boolean`          | `false`     | Whether button fills available width                                |
| `block`         | `boolean`          | `false`     | Alias for fullWidth                                                 |
| `uniform`       | `boolean`          | `false`     | Square/circular button (equal width and height)                     |
| `pill`          | `boolean`          | `false`     | Fully rounded corners                                               |
| `align`         | `string`           | `"auto"`    | Button alignment: `auto`, `start`, `center`, `end`, `stretch`       |
| `action`        | `object`           | -           | Action to execute on click                                          |
| `onClickAction` | `object`           | -           | Alias for action                                                    |
| `message`       | `string`           | -           | Simple message to send on click                                     |

## Variants

* `"primary"` - Primary action button (filled with brand color)
* `"secondary"` - Secondary action (subtle background)
* `"outline"` - Outlined button with transparent background
* `"ghost"` - Minimal style (text only, transparent)
* `"danger"` - Destructive action (red/error color)

## Sizes

* `"sm"` - Small button (padding: 8/14, font: 13px)
* `"md"` - Medium button (padding: 12/18, font: 15px) - default
* `"lg"` - Large button (padding: 16/24, font: 17px)
* `"xl"` - Extra large button (padding: 18/28, font: 18px)

## Examples

### Basic Buttons

```jsx theme={null}
<Button label="Submit" variant="primary" />
<Button label="Cancel" variant="secondary" />
<Button label="Delete" variant="danger" />
<Button label="Learn More" variant="ghost" />
<Button label="Sign Up" variant="outline" />
```

### Custom Colors

```jsx theme={null}
{/* Custom background and text color */}
<Button label="Custom" color="#8B5CF6" textColor="#FFFFFF" />

{/* Custom with shadow */}
<Button label="Elevated" color="#10B981" shadow="md" />

{/* Custom border */}
<Button
  label="Bordered"
  variant="outline"
  borderColor="#F59E0B"
  textColor="#F59E0B"
/>
```

### With Icons

```jsx theme={null}
<Button label="Add Item" icon="plus" variant="primary" />
<Button label="Download" iconEnd="download" variant="secondary" />
<Button icon="settings" uniform />
```

### Sizes

```jsx theme={null}
<Row gap="md">
  <Button label="Small" size="sm" />
  <Button label="Medium" size="md" />
  <Button label="Large" size="lg" />
  <Button label="Extra Large" size="xl" />
</Row>
```

### Shape Variants

```jsx theme={null}
{/* Pill shape (fully rounded) */}
<Button label="Pill Button" pill />

{/* Uniform (square/circular) */}
<Button icon="plus" uniform />

{/* Uniform pill (circular) */}
<Button icon="heart" uniform pill />
```

### Loading State

```jsx theme={null}
<Button label="Saving..." loading variant="primary" />
```

### Full Width

```jsx theme={null}
<Button label="Continue" fullWidth />
{/* or */}
<Button label="Continue" block />
```

### With Actions

```jsx theme={null}
{/* Send a message */}
<Button
  label="Submit"
  action={{
    type: "lyzn.sendMessage",
    payload: { message: "Form submitted" }
  }}
/>

{/* Simple message shorthand */}
<Button label="Say Hello" message="Hello!" />

{/* Show toast */}
<Button
  label="Save"
  action={{
    type: "lyzn.showToast",
    payload: { message: "Saved!", type: "success" }
  }}
/>

{/* Open link */}
<Button
  label="Visit Website"
  action={{
    type: "lyzn.openLink",
    payload: { url: "https://example.com", external: true }
  }}
/>
```

### Button Groups

```jsx theme={null}
<Row gap="md" justify="end">
  <Button label="Cancel" variant="ghost" />
  <Button label="Save" variant="primary" />
</Row>
```

### Aligned Buttons

```jsx theme={null}
<Col gap="md">
  <Button label="Start" align="start" />
  <Button label="Center" align="center" />
  <Button label="End" align="end" />
</Col>
```

## Common Patterns

### Form Actions

```jsx theme={null}
<Card>
  <Col gap="md">
    <Input name="email" label="Email" type="email" />
    <Row gap="md" justify="end">
      <Button label="Cancel" variant="secondary" />
      <Button
        label="Submit"
        variant="primary"
        action={{ type: "lyzn.sendMessage" }}
      />
    </Row>
  </Col>
</Card>
```

### Confirmation Dialog

```jsx theme={null}
<Card>
  <Col gap="md">
    <Title value="Delete Item?" />
    <Text value="This action cannot be undone." color="muted" />
    <Row gap="md" justify="end">
      <Button label="Cancel" variant="ghost" />
      <Button
        label="Delete"
        variant="danger"
        icon="trash"
        action={{ type: "lyzn.sendMessage", payload: { message: "Confirmed delete" }}}
      />
    </Row>
  </Col>
</Card>
```

### Icon-Only Toolbar

```jsx theme={null}
<Row gap="sm">
  <Button icon="bold" uniform variant="ghost" />
  <Button icon="italic" uniform variant="ghost" />
  <Button icon="underline" uniform variant="ghost" />
  <Divider direction="vertical" />
  <Button icon="list" uniform variant="ghost" />
  <Button icon="link" uniform variant="ghost" />
</Row>
```