Switch

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

Import

ts
import { Switch } from "@kobalte/core";

ts
import { Switch } from "@kobalte/core";

Features

• Follow the WAI ARIA 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.Root: 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.

tsx
<Switch.Root>
	<Switch.Label />
	<Switch.Description />
	<Switch.ErrorMessage />
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch.Root>

tsx
<Switch.Root>
	<Switch.Label />
	<Switch.Description />
	<Switch.ErrorMessage />
	<Switch.Input />
	<Switch.Control>
		<Switch.Thumb />
	</Switch.Control>
</Switch.Root>

Example

Usage

Default checked

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

tsx
<Switch.Root defaultChecked>...</Switch.Root>

tsx
<Switch.Root defaultChecked>...</Switch.Root>

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.

tsx
import { createSignal } from "solid-js";
export function ControlledExample() {
	const [checked, setChecked] = createSignal(false);
	return (
		<>
			<Switch.Root checked={checked()} onChange={setChecked}>
				...
			</Switch.Root>
			<p>Airplane mode is {checked() ? "active" : "inactive"}.</p>
		</>
	);
}

tsx
import { createSignal } from "solid-js";
export function ControlledExample() {
	const [checked, setChecked] = createSignal(false);
	return (
		<>
			<Switch.Root checked={checked()} onChange={setChecked}>
				...
			</Switch.Root>
			<p>Airplane mode is {checked() ? "active" : "inactive"}.</p>
		</>
	);
}

Description

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

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

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

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).

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);
	return (
		<Switch.Root
			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.Root>
	);
}

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);
	return (
		<Switch.Root
			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.Root>
	);
}

HTML forms

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

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

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

API Reference

Switch.Root

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

Switch.ErrorMessage

Rendered elements

Accessibility

Keyboard Interactions