# Switch

A control that allows users to choose one of two values: on or off.

## Import

```
Copyts
import { Switch } from "@kobalte/core/switch";
// or
import { Root, Input, ... } from "@kobalte/core/switch";
// or (deprecated)
import { Switch } from "@kobalte/core";
```

```
Copyts
import { Switch } from "@kobalte/core/switch";
// or
import { Root, Input, ... } from "@kobalte/core/switch";
// or (deprecated)
import { Switch } from "@kobalte/core";
```

## Features

- Follow the [WAI ARIA Switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) design pattern.
- Built with a native HTML `<input>` element, which is visually hidden to allow custom styling.
- Syncs with form reset events.
- Labeling support for assistive technology.
- Support for description and error message help text linked to the input via ARIA.
- Can be controlled or uncontrolled.

## Anatomy

The switch consists of:

- **Switch:** The root container for a switch.
- **Switch.Input:** The native html input that is visually hidden in the switch.
- **Switch.Control:** The element that visually represents a switch.
- **Switch.Thumb:** The thumb that is used to visually indicate whether the switch is on or off.
- **Switch.Label:** The label that gives the user information on the switch.
- **Switch.Description**: The description that gives the user more information on the switch.
- **Switch.ErrorMessage**: The error message that gives the user information about how to fix a validation error on the switch.

```
Copytsx
<Switch>
	<Switch.Label />
	<Switch.Description />
	<Switch.ErrorMessage />
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch>
```

```
Copytsx
<Switch>
	<Switch.Label />
	<Switch.Description />
	<Switch.ErrorMessage />
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch>
```

## Example

Airplane mode

index.tsxstyle.css

```
Copytsx
import { Switch } from "@kobalte/core/switch";
import "./style.css";

function App() {
  return (
    <Switch class="switch">
      <Switch.Label class="switch__label">Airplane mode</Switch.Label>
      <Switch.Input class="switch__input" />
      <Switch.Control class="switch__control">
        <Switch.Thumb class="switch__thumb" />
      </Switch.Control>
    </Switch>
  );
}
```

```
Copytsx
import { Switch } from "@kobalte/core/switch";
import "./style.css";

function App() {
  return (
    <Switch class="switch">
      <Switch.Label class="switch__label">Airplane mode</Switch.Label>
      <Switch.Input class="switch__input" />
      <Switch.Control class="switch__control">
        <Switch.Thumb class="switch__thumb" />
      </Switch.Control>
    </Switch>
  );
}
```

## Usage

### Default checked

An initial, uncontrolled value can be provided using the `defaultChecked` prop.

Airplane mode

```
Copytsx
<Switch defaultChecked>...</Switch>
```

```
Copytsx
<Switch defaultChecked>...</Switch>
```

### Controlled checked

The `checked` prop can be used to make the checked state controlled. The `onChange` event is fired when the user toggle the switch, and receives the new value.

Airplane mode

Airplane mode is inactive.

```
Copytsx
import { createSignal } from "solid-js";

export function ControlledExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<>
			<Switch checked={checked()} onChange={setChecked}>
				...
			</Switch>
			<p>Airplane mode is {checked() ? "active" : "inactive"}.</p>
		</>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

export function ControlledExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<>
			<Switch checked={checked()} onChange={setChecked}>
				...
			</Switch>
			<p>Airplane mode is {checked() ? "active" : "inactive"}.</p>
		</>
	);
}
```

### Description

The `Switch.Description` component can be used to associate additional help text with a switch.

Airplane mode

Disable all network connections.

```
Copytsx
<Switch>
	<Switch.Label>Airplane mode</Switch.Label>
	<Switch.Description>Disable all network connections.</Switch.Description>
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch>
```

```
Copytsx
<Switch>
	<Switch.Label>Airplane mode</Switch.Label>
	<Switch.Description>Disable all network connections.</Switch.Description>
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch>
```

### Error message

The `Switch.ErrorMessage` component can be used to help the user fix a validation error. It should be combined with the `validationState` prop to semantically mark the switch as invalid for assistive technologies.

By default, it will render only when the `validationState` prop is set to `invalid`, use the `forceMount` prop to always render the error message (ex: for usage with animation libraries).

Airplane mode

You must enable airplane mode.

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<Switch
			checked={checked()}
			onChange={setChecked}
			validationState={!checked() ? "invalid" : "valid"}
		>
			<Switch.Label>Airplane mode</Switch.Label>
			<Switch.ErrorMessage>You must enable airplane mode.</Switch.ErrorMessage>
			<Switch.Input />
			<Switch.Control>
				<Switch.Thumb />
			</Switch.Control>
		</Switch>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<Switch
			checked={checked()}
			onChange={setChecked}
			validationState={!checked() ? "invalid" : "valid"}
		>
			<Switch.Label>Airplane mode</Switch.Label>
			<Switch.ErrorMessage>You must enable airplane mode.</Switch.ErrorMessage>
			<Switch.Input />
			<Switch.Control>
				<Switch.Thumb />
			</Switch.Control>
		</Switch>
	);
}
```

### HTML forms

The `name` and `value` props can be used for integration with HTML forms.

Airplane mode

ResetSubmit

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<Switch name="airplane-mode" value="on">
				...
			</Switch>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<Switch name="airplane-mode" value="on">
				...
			</Switch>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

## API Reference

### Switch

`Switch` is equivalent to the `Root` import from `@kobalte/core/switch` (and deprecated `Switch.Root`).

| Prop | Description |
| --- | --- |
| checked | `boolean`<br> The controlled checked state of the switch. |
| defaultChecked | `boolean`<br> The default checked state when initially rendered. Useful when you do not need to control the checked state. |
| onChange | `(checked: boolean) => void`<br> Event handler called when the checked state of the switch changes. |
| name | `string`<br> The name of the switch, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| value | `string`<br> The value of the switch, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| validationState | `'valid' | 'invalid'`<br> Whether the switch should display its "valid" or "invalid" visual styling. |
| required | `boolean`<br> Whether the user must check the switch before the owning form can be submitted. |
| disabled | `boolean`<br> Whether the switch is disabled. |
| readOnly | `boolean`<br> Whether the switch can be checked but not changed by the user. |

| Render Prop | Description |
| --- | --- |
| checked | `Accessor<boolean>`<br> Whether the switch is checked or not. |

| Data attribute | Description |
| --- | --- |
| data-valid | Present when the switch is valid according to the validation rules. |
| data-invalid | Present when the switch is invalid according to the validation rules. |
| data-required | Present when the switch is required. |
| data-disabled | Present when the switch is disabled. |
| data-readonly | Present when the switch is read only. |
| data-checked | Present when the switch is checked. |

`Switch.Input`, `Switch.Control`, `Switch.Thumb`, `Switch.Label`, `Switch.Description` and `Switch.ErrorMessage` shares the same data-attributes.

### Switch.ErrorMessage

| Prop | Description |
| --- | --- |
| forceMount | `boolean`<br> Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries. |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `Switch` | `div` |
| `Switch.Input` | `input` |
| `Switch.Control` | `div` |
| `Switch.Indicator` | `div` |
| `Switch.Label` | `label` |
| `Switch.Description` | `div` |
| `Switch.ErrorMessage` | `div` |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `Space` | Toggles the switch on and off. |

Previous[←Slider](https://kobalte.dev/docs/core/components/slider)Next[Tabs→](https://kobalte.dev/docs/core/components/tabs)