Switch

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

Notifications

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

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

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-solid/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 (for/id).

Sibling label pattern with a native button

<div>
  <label for="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.

Prop

Type

Default

namestring—

Identifies the field when a form is submitted.string

defaultCheckedbooleanfalse

Whether the switch is initially active. To render a controlled switch, use the checked prop instead.boolean

checkedboolean—

Whether the switch is currently active. To render an uncontrolled switch, use the defaultChecked prop instead.boolean

onCheckedChangefunction—

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

valuestring—

The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.string

formstring—

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.string

nativeButtonbooleanfalse

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

uncheckedValuestring—

The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.string

disabledbooleanfalse

Whether the component should ignore user interaction.boolean

readOnlybooleanfalse

Whether the user should be unable to activate or deactivate the switch.boolean

requiredbooleanfalse

Whether the user must activate the switch before submitting a form.boolean

inputRefRef<HTMLInputElement>—

A ref to access the hidden <input> element.Ref<HTMLInputElement>

idstring—

The id of the hidden input element. When nativeButton is true, the id is applied to the root element.string

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

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

Root.State

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;
};

Root.ChangeEventReason

type SwitchRootChangeEventReason = 'none';

Root.ChangeEventDetails

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

Prop

Type

Default

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

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

Thumb.State

type SwitchThumbState = {
  /** 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;
};