# Button

An action control aligned with the Nesra Button design.

Button uses Base UI behavior and Nesra’s Light and Dark color roles.

## Usage

```tsx
import { Button } from "@nesra/ui/button";

export function SaveButton() {
  return <Button>Save changes</Button>;
}
```

`Button` is also exported from `@nesra/ui`.

For navigation that should look like a button, style a native anchor with the exported `buttonVariants` helper. This preserves link semantics and browser link behavior:

```tsx
import { buttonVariants } from "@nesra/ui/button";

export function ReportsLink() {
  return (
    <a className={buttonVariants({ variant: "outline", size: "md" })} href="/reports">
      View reports
    </a>
  );
}
```

## Examples

### Variants

```tsx
import { Button } from "@nesra/ui/button";

export function ButtonVariantsExample() {
  return (
    <>
      <Button>Primary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="link">Link</Button>
    </>
  );
}
```

### Sizes

`sm`, `md`, and `lg` are 32, 40, and 44px tall. `icon-*` sizes are square. Default: `md`.

```tsx
import { Button } from "@nesra/ui/button";

export function ButtonSizesExample() {
  return (
    <>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </>
  );
}
```

### Icons

`startIcon` and `endIcon` are decorative. Icon-only buttons need an accessible name.

```tsx
import { Button } from "@nesra/ui/button";
import { ArrowRight, CircleCheck } from "lucide-react";

export function ButtonIconsExample() {
  return (
    <>
      <Button startIcon={<CircleCheck size={20} />}>Save</Button>
      <Button endIcon={<ArrowRight size={20} />} variant="outline">
        Continue
      </Button>
      <Button aria-label="Confirm" size="icon-sm">
        <CircleCheck aria-hidden="true" size={16} />
      </Button>
      <Button aria-label="Confirm" size="icon-md">
        <CircleCheck aria-hidden="true" size={20} />
      </Button>
      <Button aria-label="Confirm" size="icon-lg">
        <CircleCheck aria-hidden="true" size={20} />
      </Button>
    </>
  );
}
```

### Loading and disabled

`loading` sets `aria-busy` and prevents activation. It hides the child of an icon-only button, so keep its `aria-label`.

```tsx
import { Button } from "@nesra/ui/button";

export function ButtonStatesExample() {
  return (
    <>
      <Button loading>Submitting</Button>
      <Button disabled>Unavailable</Button>
      <Button loading variant="outline">
        Submitting
      </Button>
    </>
  );
}
```

## Light and Dark

Button follows the page theme. Dark applies when an ancestor has the `dark` class or `data-theme="dark"`. No prop is needed.

*   **Primary** uses `Action/primary-default` with `Text/text-on-brand` and `Icon/icon-on-brand`. It is near-black with white content in Light and near-white with near-black content in Dark.
*   **Destructive** keeps `Text/text-staticWhite` on `Action/destructive-default` in both modes, because the red fill does not change.
*   **Outline**, **Ghost**, and **Link** use `Text/text-body` or `Text/text-link` on mode-aware surfaces. Ghost has a transparent fill (`Action/tertiary-default`). Link hovers and focuses with `Categorical/Blue/subtle`, and its icons use `Icon/icon-info`.
*   **Disabled** buttons use `Text/text-disabled` and `Icon/icon-disabled`. Primary, Outline, and Destructive sit on `Action/primary-disabled`; Ghost and Link have no fill.
*   **Loading** Outline, Ghost, and Link buttons use `Text/text-support`. Primary and Destructive keep their default fill and content colors.
*   **Focus** uses `Box Shadow/Focus ring offset` (`shadow-nesra-focus-ring-offset`) in every variant: a 2px `Foundation/bg-neutral` gap, then a 2px `Effects/focus-ring` ring.

## Accessibility

*   Use an anchor for navigation. The `link` variant changes appearance, not button semantics.
*   Use `type="button"` for an in-page action inside a form and `type="submit"` when the button submits that form. `Button` defaults to `type="button"`.
*   Keep the keyboard focus state visible when extending styles.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "outline" \| "ghost" \| "destructive" \| "link"` | `"primary"` | Visual style. |
| `size` | `"sm" \| "md" \| "lg" \| "icon-sm" \| "icon-md" \| "icon-lg"` | `"md"` | Height and padding. Icon sizes are square. |
| `children` | `ReactNode` | — | Label or icon-only content. |
| `startIcon` | `ReactNode` | — | Decorative icon before the label. |
| `endIcon` | `ReactNode` | — | Decorative icon after the label. |
| `loading` | `boolean` | `false` | Shows a loader, sets `aria-busy`, and prevents activation. |
| `disabled` | `boolean` | `false` | Prevents interaction. |
| `className` | `string` | — | Adds or overrides classes. |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button behavior in forms. |

Other Base UI Button props and native button attributes, such as `onClick` and `aria-label`, are forwarded. A ref points to the button element. `buttonVariants` accepts the same `variant` and `size` values and returns a class string for styling another element. It does not add button behavior. The Button’s visual values come from the [semantic color roles](/colors/) and [shape and elevation tokens](/shape-and-elevation/).
