Components

Switch

A control that turns a setting on or off

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

A setting that applies the moment it changes. No Nyte styling on this one, you own the visual layer.

Usage

Give the switch an accessible name. A wrapping <label> is the simplest pattern.
Switch.Root renders a <span> by default, so an enclosing label works. Render a native <button> when you use a sibling label with htmlFor and id.
A switch commits on change. If the setting needs a save step, use a checkbox instead.
The on value is submitted by default. Set value to change it, and uncheckedValue to submit something when the switch is off.

Anatomy

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

Examples

A wrapping label

Notifications

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

A sibling label

With htmlFor and id, render the root as a native button and tell Base UI about it.

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

A native button inside a label

A <button> inside a <label> is invalid HTML, so the render callback places the hidden input outside the label.

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

Controlled

const [enabled, setEnabled] = useState(false);

<Switch.Root checked={enabled} onCheckedChange={setEnabled}>
  <Switch.Thumb />
</Switch.Root>;

Props

The reference tables below come from Base UI, MIT, © Material-UI SAS.

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

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

Accessibility

The root carries role="switch" and aria-checked. Space and Enter toggle it.
id lands on the hidden input, or on the root when nativeButton is true.
readOnly keeps the switch focusable and blocks the change. disabled removes it from the tab order.
Both parts reflect data-checked, data-unchecked, data-disabled, data-readonly, and data-required, so the thumb can animate from CSS alone.