Switch

A control element that allows for a binary selection.

Label

Anatomy

<Switch.Root>
  <Switch.Control>
    <Switch.Thumb />
  </Switch.Control>
  <Switch.Label />
  <Switch.HiddenInput />
</Switch.Root>

Examples

Controlled

For a controlled Switch component, the state of the toggle is managed using the checked prop, and updates when the onCheckedChange event handler is called:

Root Provider

An alternative way to control the switch is to use the RootProvider component and the useSwitch hook. This way you can access the state and methods from outside the component.

Field

The Field component helps manage form-related state and accessibility attributes of a switch. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Context

The Switch component allows access to its internal state through the Context component. This enables you to dynamically adjust and customize aspects of the component based on its current state:

Guides

asChild

The Switch.Root element of the switch is a label element. This is because the switch is a form control and should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will be invalid.

If you need to use the asChild property, make sure that the label element is the direct child of the Switch.Root component.

API Reference

Props

Root

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`checked`		`boolean` The controlled checked state of the switch
`disabled`		`boolean` Whether the switch is disabled.
`ids`		`Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` The ids of the elements in the switch. Useful for composition.
`invalid`		`boolean` If `true`, the switch is marked as invalid.
`label`		`string` Specifies the localized strings that identifies the accessibility elements and their states
`name`		`string` The name of the input field in a switch (Useful for form submission).
`onCheckedChange`		`(details: CheckedChangeDetails) => void` Function to call when the switch is clicked.
`readOnly`		`boolean` Whether the switch is read-only
`required`		`boolean` If `true`, the switch input is marked as required,
`value`	`'on'`	`string \| number` The value of switch input. Useful for form submission.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

Control

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Label

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

RootProvider

Renders a <label> element.

Prop	Default	Type
`value`		`UseSwitchReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Thumb

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

Context

API

Property	Type
`checked`	`boolean` Whether the switch is checked
`disabled`	`boolean` Whether the switch is disabled
`focused`	`boolean` Whether the switch is focused
`setChecked`	`(checked: boolean) => void` Sets the checked state of the switch.
`toggleChecked`	`VoidFunction` Toggles the checked state of the switch.

Accessibility

Complies with the Switch WAI-ARIA design pattern.

Keyboard Support

Key	Description
`SpaceEnter`	Toggle the switch