PettyUI/.firecrawl/kobalte.dev-docs-core-components-switch.md

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 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 The controlled checked state of the switch.
defaultChecked	boolean The default checked state when initially rendered. Useful when you do not need to control the checked state.
onChange	(checked: boolean) => void Event handler called when the checked state of the switch changes.
name	string The name of the switch, used when submitting an HTML form. See MDN.
value	string The value of the switch, used when submitting an HTML form. See MDN.
validationState	`'valid'
required	boolean Whether the user must check the switch before the owning form can be submitted.
disabled	boolean Whether the switch is disabled.
readOnly	boolean Whether the switch can be checked but not changed by the user.

Render Prop	Description
checked	Accessor<boolean> 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 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←SliderNextTabs→