---
title: Button
description: Buttons trigger actions in the interface. Choose a variant that reflects importance.
category: Actions
---

import { meta as ButtonMeta, Default, Destructive, Ghost, Link } from '@/content/stories/button';
import Canvas from '@/components/component-docs/canvas';
import Demo from '@/components/component-docs/demo';

export const config = {
	dependencies: {
		components: [Canvas, Demo],
		scripts: [
			'../../components/component-docs/demo.script.tsx',
			'../../components/component-docs/canvas.script.tsx',
			'../../components/component-docs/controls.script.tsx',
		],
	},
};


# Button

<p class="docs-lede">Buttons trigger actions in the interface. Choose a variant that reflects importance, and write labels that describe the outcome, not the control type.</p>

## Try it

<Demo of={Default} meta={ButtonMeta} />

## Usage

Import `RuiButton` from the focused module. The default `filled` variant suits the primary action in a small context.

```tsx
import { RuiButton } from '@ecopages/radiant-ui/button';

<RuiButton variant="filled" size="md">
	Save changes
</RuiButton>
```

## Choose a tone

Use `filled` for the main action, `outline` for a supporting action, and `ghost` when the action should recede until needed. `link` looks like inline navigation copy and underlines on hover and focus; pair it with `size="none"` in running text. `destructive` is for irreversible operations.

Pass `href` when the control should navigate; `variant` only changes appearance.

Use the `square` modifier for an icon-only action. It keeps the selected control size on both axes; provide an `aria-label` because it has no visible text.

```tsx
<RuiButton size="sm" square aria-label="Add item">
	<AddIcon />
</RuiButton>
```

<Canvas of={Destructive} meta={ButtonMeta} />
<br />
<Canvas of={Ghost} meta={ButtonMeta} />
<br />
<Canvas of={Link} meta={ButtonMeta} />

## Theming

Button variants map to **semantic action roles** from the active theme, not Tailwind palette steps (`blue-500`, `red-500`, …):

| `variant` | Semantic role | Typical utilities on `.rui-button--*` |
| --- | --- | --- |
| `filled` | `primary` | `bg-primary`, `text-on-primary` |
| `outline` | surface + `border` | `bg-transparent`, `text-on-background`, `border-border` |
| `ghost` | surface-container | `bg-transparent`, `text-on-surface`, hover `bg-surface-container-low` |
| `destructive` | `error` (destructive) | `bg-error`, `text-on-error` |
| `link` | `link` | `text-link`, underline on hover/focus |

Pressed (toggle) states keep the same role family with a stronger fill (`bg-primary-dark`, `bg-error-dark`) and a focus ring. Brand color packs remap all roles for light and dark mode.

Override at the theme layer (`tokens/presets/colors/*.css`), not in component CSS. `destructive` reuses the `error` status family, matching alerts and toasts.

## Accessibility

- Write labels that describe the resulting action, such as "Save changes".
- Keep disabled buttons explainable with nearby supporting text when needed.
- Do not use color as the only way to communicate action priority or status.
- Set `aria-label` when a button has no visible text (icon-only buttons).
- Toggle buttons set `aria-pressed` when `toggle` / `pressed` are used.

## API

`RuiButton` is a presentational JSX view over a native `<button>` or `<a>`, no custom element. `RuiButtonProps` is a union: pass `href` to render a link, otherwise a button.

### Shared props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `filled` · `outline` · `destructive` · `ghost` · `link` | `filled` | Visual tone. |
| `size` | `none` · `sm` · `md` · `lg` | `md` | Control size; `none` for inline `link` chrome. |
| `square` | `boolean` | `false` | Makes the selected control size square for icon-only actions. |
| `aria-label` | `string` | | Accessible name when there is no visible text. |

### Button branch props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `button` · `submit` · `reset` | `button` | Native button type. |
| `disabled` | `boolean` | `false` | Disabled state. |
| `pressed` | `boolean` | | Controlled `aria-pressed` (toggle buttons). |
| `defaultPressed` | `boolean` | `false` | Initial pressed state for uncontrolled toggles. |
| `toggle` | `boolean` | `false` | Toggle `aria-pressed` on click when `pressed` is uncontrolled. |

### Link branch props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | | Destination; renders `<a>` instead of `<button>`. |
| `target` | `_self` · `_blank` · `_parent` · `_top` | | Link target. |
| `rel` | `string` | | Link relationship. |
| `download` | `boolean \| string` | | Native download attribute. |
| `aria-current` | `string` | | Current-page indicator for nav links. |

### CSS classes

Public BEM classes on the rendered element (documented via `@cssclass` on `RuiButton`):

| Class | Description |
| --- | --- |
| `.rui-button` | Button / button-styled link root. |
| `.rui-button--filled` | Primary filled action. |
| `.rui-button--outline` | Bordered secondary action. |
| `.rui-button--destructive` | Destructive action. |
| `.rui-button--ghost` | Subtle, borderless action. |
| `.rui-button--link` | Inline link-styled action. |
| `.rui-button--none` | No fixed size (inline `link` chrome). |
| `.rui-button--sm` · `.rui-button--md` · `.rui-button--lg` | Control sizes. |
| `.rui-button--square` | Square control for icon-only actions. |

### Theme roles (per `variant`)

| Variant | CSS variables consumed |
| --- | --- |
| `filled` | `--primary`, `--on-primary`, `--primary-dark` |
| `outline` | `--on-background`, `--border`, `--surface` |
| `ghost` | `--on-surface`, `--surface-container-low`, `--surface-container` |
| `destructive` | `--error`, `--on-error`, `--error-dark` |
| `link` | `--link` |