Switch

A high-quality, unstyled React switch component that indicates whether a setting is on or off.

A control that indicates whether a setting is on or off.

Notifications

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See Labeling a switch and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Switch } from '@base-ui/react/switch';

<Switch.Root>
  <Switch.Thumb />
</Switch.Root>;

Examples

Labeling a switch

An enclosing <label> is the simplest labeling pattern:

Wrapping a label around a switch

<label>
  <Switch.Root />
  Notifications
</label>

Rendering as a native button

By default, <Switch.Root> renders a <span> element to support enclosing labels. Prefer rendering the switch as a native button when using sibling labels (htmlFor/id).

Sibling label pattern with a native button

<div>
  <label htmlFor="notifications-switch">Notifications</label>
  <Switch.Root id="notifications-switch" nativeButton render={<button />}>
    <Switch.Thumb />
  </Switch.Root>
</div>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

Render callback

<Switch.Root
  nativeButton
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Notifications
    </label>
  )}
/>

Form integration

Use Field to handle label associations and form integration:

Using Switch in a form

<Form>
  <Field.Root name="notifications">
    <Field.Label>
      <Switch.Root />
      Notifications
    </Field.Label>
  </Field.Root>
</Form>

API reference

Root

Name	Type	Default	Description
`id`Optional	`string \| undefined`	—	The id of the switch element.
`checked`Optional	`boolean \| undefined`	—	Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead.
`defaultChecked`Optional	`boolean \| undefined`	`false`	Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead.
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction.
`inputRef`Optional	`React.Ref<HTMLInputElement> \| undefined`	—	A ref to access the hidden `<input>` element.
`name`Optional	`string \| undefined`	—	Identifies the field when a form is submitted.
`readOnly`Optional	`boolean \| undefined`	`false`	Whether the user should be unable to activate or deactivate the switch.
`required`Optional	`boolean \| undefined`	`false`	Whether the user must activate the switch before submitting a form.
`value`Optional	`string \| undefined`	—	The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.
`uncheckedValue`Optional	`string \| undefined`	—	The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.

Switch

Usage guidelines

Anatomy

Examples

Labeling a switch

Rendering as a native button

Form integration

API reference

Root

On this page