Headless

Switch

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

In Nyte

Import

import { Switch } from "@nyte-ai/ui/switch";

@nyte-ai/ui/switch re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

desktop/src/renderer/src/chrome/settings-controls.tsx

The rest of this page is Base UI's documentation for @base-ui/react/switch, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above.

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

// @highlight
<label>
  <Switch.Root />
  Notifications
  {/* @highlight */}
</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>
  {/* @highlight-text "nativeButton" "render={<button />}" */}
  <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
  // @highlight-start
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Notifications
    </label>
  )}
  {/* @highlight-end */}
/>

Form integration

Use Field to handle label associations and form integration:

Using Switch in a form

<Form>
  {/* @highlight */}
  <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.

Root Props:

Prop	Type	Default	Description
name	`string`	-	Identifies the field when a form is submitted.
defaultChecked	`boolean`	`false`	Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead.
checked	`boolean`	-	Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead.
onCheckedChange	`((checked: boolean, eventDetails: Switch.Root.ChangeEventDetails) => void)`	-	Event handler called when the switch is activated or deactivated.
value	`string`	-	The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.
form	`string`	-	Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
nativeButton	`boolean`	`false`	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.
uncheckedValue	`string`	-	The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
readOnly	`boolean`	`false`	Whether the user should be unable to activate or deactivate the switch.
required	`boolean`	`false`	Whether the user must activate the switch before submitting a form.
inputRef	`React.Ref<HTMLInputElement>`	-	A ref to access the hidden `<input>` element.
id	`string`	-	The id of the hidden input element. When `nativeButton` is `true`, the id is applied to the root element.
className	`string \| ((state: Switch.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Switch.Root.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Switch.Root.State) => ReactElement)`	-	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.

Root Data Attributes:

Attribute	Type	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.Props

Re-export of Root props.

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

Thumb Props:

Prop	Type	Default	Description
className	`string \| ((state: Switch.Thumb.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Switch.Thumb.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Switch.Thumb.State) => ReactElement)`	-	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.

Thumb Data Attributes:

Attribute	Type	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.Props

Re-export of Thumb props.

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

Export Groups

Switch.Root: Switch.Root, Switch.Root.State, Switch.Root.Props, Switch.Root.ChangeEventReason, Switch.Root.ChangeEventDetails
Switch.Thumb: Switch.Thumb, Switch.Thumb.Props, Switch.Thumb.State
Default: SwitchRootState, SwitchRootProps, SwitchRootChangeEventReason, SwitchRootChangeEventDetails, SwitchThumbProps, SwitchThumbState

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

Switch.Root.State: SwitchRootState
Switch.Root.Props: SwitchRootProps
Switch.Root.ChangeEventReason: SwitchRootChangeEventReason
Switch.Root.ChangeEventDetails: SwitchRootChangeEventDetails
Switch.Thumb.Props: SwitchThumbProps
Switch.Thumb.State: SwitchThumbState