---
title: "Button"
description: "Triggers an action or submits a form."
category: "Form & Input"
slug: button
url: /components/button
since: "0.1.0"
status: "stable"
---

# Button

Triggers an action or submits a form.

## Import

```svelte
import { Button } from '@elluzion/iv-ui';
```

## Preview

Six levels of emphasis. `secondary` is the default.

```svelte
<script lang="ts">
	import { IconDots } from '@tabler/icons-svelte';
	import { Button } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button variant="primary">Primary</Button>
	<Button>Secondary</Button>
	<Button variant="outline">Outline</Button>
	<Button variant="ghost">Ghost</Button>
	<Button variant="danger">Danger</Button>
	<Button variant="icon" aria-label="More actions"><IconDots size={16} /></Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

## Usage

- Keep one primary action per view; everything else stays `secondary` or `outline`.
- Use `loading` for async work — it sets `aria-busy` and ignores clicks without removing the button from the tab order.
- Icon-only buttons need an `aria-label`; the `icon` variant has no text to fall back on.

## Examples

### Sizes

`sm`, `md`, and `lg` share the same shape.

```svelte
<script lang="ts">
	import { IconPlus } from '@tabler/icons-svelte';
	import { Button } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button size="sm" variant="primary">Small</Button>
	<Button size="md" variant="primary">Medium</Button>
	<Button size="lg" variant="primary">Large</Button>
</div>
<div class="row">
	<Button size="sm" variant="outline"><IconPlus size={14} /> New</Button>
	<Button size="md" variant="outline"><IconPlus size={16} /> New</Button>
	<Button size="lg" variant="outline"><IconPlus size={18} /> New</Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Icons

Icons inherit the text size. Icon-only buttons use `variant="icon"`.

```svelte
<script lang="ts">
	import { IconArrowRight, IconDownload, IconSearch, IconTrash } from '@tabler/icons-svelte';
	import { Button } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button variant="primary"><IconDownload size={16} /> Export</Button>
	<Button variant="outline">Continue <IconArrowRight size={16} /></Button>
	<Button variant="ghost"><IconSearch size={16} /> Search</Button>
	<Button variant="danger"><IconTrash size={16} /> Delete</Button>
</div>
<div class="row">
	<Button variant="icon" aria-label="Search"><IconSearch size={18} /></Button>
	<Button variant="icon" aria-label="Export"><IconDownload size={18} /></Button>
	<Button variant="icon" aria-label="Delete" disabled><IconTrash size={18} /></Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Loading

Spinner replaces the label and clicks are ignored while `loading` is true.

```svelte
<script lang="ts">
	import { Button } from '@elluzion/iv-ui';

	let saving = $state(false);

	async function save() {
		saving = true;
		await new Promise((resolve) => setTimeout(resolve, 1200));
		saving = false;
	}
</script>

<div class="row">
	<Button variant="primary" loading={saving} onclick={save}>
		{saving ? 'Saving…' : 'Save changes'}
	</Button>
	<Button variant="outline" loading>Syncing</Button>
	<Button variant="secondary" disabled>Unavailable</Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Events

`onclick` and the legacy `on:click` both receive the native mouse event.

```svelte
<script lang="ts">
	import { Button } from '@elluzion/iv-ui';

	let clicks = $state(0);
	let legacy = $state(0);

	// Both props receive the same native event.
	const handlers = {
		onclick: () => clicks++,
		'on:click': () => legacy++
	};
</script>

<div class="stack">
	<Button variant="primary" {...handlers}>Click me</Button>
	<p class="readout">onclick {clicks} · on:click {legacy}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-size: var(--iv_text-xs);
		color: var(--iv_foreground-dim);
		font-variant-numeric: tabular-nums;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'icon' \| 'danger'` | `'secondary'` | Visual emphasis. `secondary` is the default. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button height and padding. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `loading` | `boolean` | `false` | Shows a spinner, sets `aria-busy`, and ignores clicks. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native button type. |

All native `<button>` attributes are forwarded.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent) => void` | Called on activation with the native mouse event. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |

### Tokens used

`--iv_border` · `--iv_border-hover` · `--iv_btn-pad-x` · `--iv_btn-pad-x-lg` · `--iv_btn-pad-x-sm` · `--iv_control-pad-y` · `--iv_control-pad-y-lg` · `--iv_control-pad-y-sm` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_ease-out` · `--iv_error` · `--iv_error-dim` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_foreground-hover` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface` · `--iv_surface-elevated` · `--iv_surface-hover` · `--iv_surface-raised` · `--iv_text-btn-sm` · `--iv_text-lg` · `--iv_transition-base` · `--iv_transition-fast`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-btn-lg` · `.iv-btn-sm` · `.iv-danger` · `.iv-disabled` · `.iv-ghost` · `.iv-icon` · `.iv-loading` · `.iv-outline` · `.iv-primary`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the button. |
| `Enter` | Activates the button. |
| `Space` | Activates the button. |

- Focus uses a visible ring; it is never removed.
- A disabled button is removed from the tab order and does not fire clicks.

## Related

- [ButtonGroup](/components/button-group.md)
- [Toggle](/components/toggle.md)
- [Field](/components/field.md)
- [Tooltip](/components/tooltip.md)