---
title: "Switch"
description: "An on/off control that applies immediately."
category: "Form & Input"
slug: switch
url: /components/switch
since: "0.1.0"
status: "stable"
---

# Switch

An on/off control that applies immediately.

## Import

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

## Preview

A labelled switch with a bound state.

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

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

<div class="stack">
	<Switch label="Send anonymous telemetry" bind:checked={telemetry} />
	<p class="readout">telemetry {telemetry ? 'on' : 'off'}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		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

- Bind `checked`; changes apply without a submit step.
- Use `label` for the visible and accessible name.
- Prefer `Checkbox` when the choice is part of a form that is submitted later.

## Examples

### Sizes

`sm` and `md` keep the same hit area.

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

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

<div class="stack">
	<Switch label="Small" size="sm" bind:checked={a} />
	<Switch label="Medium" bind:checked={b} />
</div>

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

### Disabled

The switch is removed from interaction but keeps its value.

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

<div class="stack">
	<Switch label="Locked by policy" checked disabled />
	<Switch label="Available" />
</div>

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` **bindable** | `boolean` | `false` | On/off state. Bind with `bind:checked`. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `label` | `string` | `''` | Label rendered next to the switch. |
| `size` | `'sm' \| 'md'` | `'md'` | Control size. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ checked: boolean }>) => void` | Called with `{ checked }` after the state changes. |
| `focus` | `(e: FocusEvent) => void` | Called when the control receives focus. |
| `blur` | `(e: FocusEvent) => void` | Called when the control loses focus. |

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

### Tokens used

`--iv_border` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_leading-tight` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_spacing-sm` · `--iv_surface-elevated` · `--iv_switch-h` · `--iv_switch-h-sm` · `--iv_switch-w` · `--iv_switch-w-sm` · `--iv_text-body` · `--iv_thumb-md` · `--iv_thumb-sm` · `--iv_transition-fast`

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

### CSS hooks

`.iv-checked` · `.iv-disabled` · `.iv-label` · `.iv-md` · `.iv-root` · `.iv-sm` · `.iv-switch` · `.iv-thumb`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the switch. |
| `Space / Enter` | Toggles the switch. |

- The control exposes `role="switch"` with `aria-checked`.
- The label is linked through `aria-labelledby`.
- Focus is drawn on the track and is never removed.

## Related

- [Checkbox](/components/checkbox.md)
- [Toggle](/components/toggle.md)
- [Slider](/components/slider.md)
- [Field](/components/field.md)