---
title: "Toggle"
description: "A pressable button that keeps a checked state."
category: "Form & Input"
slug: toggle
url: /components/toggle
since: "0.2.0"
status: "stable"
---

# Toggle

A pressable button that keeps a checked state.

## Import

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

## Preview

A labelled toggle with a bound state.

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

	let pinned = $state(true);
</script>

<div class="stack">
	<Toggle bind:checked={pinned}>Pin to dashboard</Toggle>
	<p class="readout">pinned {pinned ? 'yes' : 'no'}</p>
</div>

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

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- Use `Toggle` for formatting and view modes; use `Switch` for settings that save immediately.
- Pass visible children or a `label` for the accessible name.
- `icon` renders before the children; the check mark appears when checked.

## Examples

### Icons

Icons inherit the current text color and size step.

```svelte
<script lang="ts">
	import { IconBold, IconItalic, IconUnderline } from '@tabler/icons-svelte';
	import { Toggle } from '@elluzion/iv-ui';

	let bold = $state(true);
	let italic = $state(false);
	let underline = $state(false);
</script>

<div class="row">
	<Toggle bind:checked={bold} label="Bold"><IconBold size={14} /></Toggle>
	<Toggle bind:checked={italic} label="Italic"><IconItalic size={14} /></Toggle>
	<Toggle bind:checked={underline} label="Underline"><IconUnderline size={14} /></Toggle>
</div>

<style>
	.row {
		display: flex;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Sizes

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

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

	let a = $state(true);
	let b = $state(true);
	let c = $state(true);
</script>

<div class="row">
	<Toggle size="sm" bind:checked={a}>Small</Toggle>
	<Toggle bind:checked={b}>Medium</Toggle>
	<Toggle size="lg" bind:checked={c}>Large</Toggle>
</div>

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` **bindable** | `boolean` | `false` | Pressed state. Bind with `bind:checked`. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `label` | `string` | `''` | Accessible name. Visible text can be passed as children instead. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |

All native `<button>` attributes are forwarded.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent) => void` | Called when the element is activated. |
| `change` | `(e: CustomEvent<{ checked: boolean }>) => void` | Called with `{ checked }` after the state changes. |

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

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `icon` | `Snippet` | Icon rendered inside the toggle. |
| `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_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_reverse-hover` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface` · `--iv_surface-elevated` · `--iv_surface-hover` · `--iv_text-btn` · `--iv_text-btn-sm` · `--iv_text-lg` · `--iv_transition-base` · `--iv_transition-fast` · `--iv_weight-semibold`

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

### CSS hooks

`.iv-check` · `.iv-checked` · `.iv-disabled` · `.iv-icon` · `.iv-lg` · `.iv-sm` · `.iv-toggle`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the toggle. |
| `Space / Enter` | Toggles the pressed state. |

- The toggle is a native button with `aria-pressed`.
- With no visible text, pass `label` so the control has an accessible name.
- Focus uses the standard button ring.

## Related

- [ToggleGroup](/components/toggle-group.md)
- [Button](/components/button.md)
- [Switch](/components/switch.md)
- [Checkbox](/components/checkbox.md)