Switch

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

Base UI React 1.8.0

Notifications

FineSoft Stencil

Notifications

react-switch.tsx stencil-switch.tsx index.module.css

import { Switch } from '@base-ui/react/switch';
import styles from './index.module.css';

export default function ExampleSwitch() {
  return (
    <label className={styles.Label}>
      <Switch.Root defaultChecked className={styles.Switch}>
        <Switch.Thumb className={styles.Thumb} />
      </Switch.Root>
      Notifications
    </label>
  );
}

Stencil boundary

fs-switch-thumb exposes its internal movable span through an open ShadowRoot and ::part(thumb). Classes remain on the host; use this part or the --fs-switch-thumb-* theme variables to style the indicator. Checked and disabled state attributes are available on the host. Inline styles continue to reach the internal span, while ordinary page selectors cannot style it directly.

fs-switch-root retains Light DOM for its native checkbox, switch control, label association, and form participation. The Base UI theme is built in; select data-fs-theme="base-ui" on an ancestor to enable the optional theme. The Root and authored Thumb content remain accessible to ordinary CSS selectors.

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

Represents the switch itself. Renders a <span> element and a hidden <input> beside.

namestring—

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

defaultCheckedbooleanfalse

Name: defaultChecked
Description: Whether the switch is initially active.

To render a controlled switch, use the checked prop instead.
Type: boolean | undefined
Default: false

checkedboolean—

Name: checked
Description: Whether the switch is currently active.

To render an uncontrolled switch, use the defaultChecked prop instead.
Type: boolean | undefined

onCheckedChangefunction—

Name: onCheckedChange
Description: Event handler called when the switch is activated or deactivated.
Type: | (( checked: boolean, eventDetails: Switch.Root.ChangeEventDetails, ) => void) | undefined

valuestring—

Name: value
Description: The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.
Type: string | undefined

formstring—

Name: form
Description: Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
Type: string | undefined

nativeButtonbooleanfalse

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
Type: boolean | undefined
Default: false

uncheckedValuestring—

Name: uncheckedValue
Description: The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
Type: string | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

readOnlybooleanfalse

Name: readOnly
Description: Whether the user should be unable to activate or deactivate the switch.
Type: boolean | undefined
Default: false

requiredbooleanfalse

Name: required
Description: Whether the user must activate the switch before submitting a form.
Type: boolean | undefined
Default: false

inputRefReact.Ref<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden <input> element.
Type: React.Ref<HTMLInputElement> | undefined

idstring—

Name: id
Description: The id of the hidden input element.

When nativeButton is true, the id is applied to the root element.
Type: string | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Switch.Root.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Switch.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Switch.Root.State, ) => ReactElement) | undefined

data-checked

Present when the switch is checked.

data-unchecked

Present when the switch is not checked.

data-disabled

Present when the switch is disabled.

data-readonly

Present when the switch is readonly.

data-required

Present when the switch is required.

data-valid

Present when the switch is in a valid state (when wrapped in Field.Root).

data-invalid

Present when the switch is in an invalid state (when wrapped in Field.Root).

data-dirty

Present when the switch’s value has changed (when wrapped in Field.Root).

data-touched

Present when the switch has been touched (when wrapped in Field.Root).

data-filled

Present when the switch is active (when wrapped in Field.Root).

data-focused

Present when the switch is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-checked`	Present when the switch is checked.
`data-unchecked`	Present when the switch is not checked.
`data-disabled`	Present when the switch is disabled.
`data-readonly`	Present when the switch is readonly.
`data-required`	Present when the switch is required.
`data-valid`	Present when the switch is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the switch is in an invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the switch’s value has changed (when wrapped in Field.Root).
`data-touched`	Present when the switch has been touched (when wrapped in Field.Root).
`data-filled`	Present when the switch is active (when wrapped in Field.Root).
`data-focused`	Present when the switch is focused (when wrapped in Field.Root).

Switch.Root.PropsHide

Re-Export of Root props as SwitchRootProps

Switch.Root.StateHide

type SwitchRootState = {
  /** Whether the switch is currently active. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to activate or deactivate the switch. */
  readOnly: boolean;
  /** Whether the user must activate the switch before submitting a form. */
  required: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
}

Switch.Root.ChangeEventReasonHide

type SwitchRootChangeEventReason = 'none'

Switch.Root.ChangeEventDetailsHide

type SwitchRootChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
}

Thumb

The movable part of the switch that indicates whether the switch is on or off. Renders a <span>.