Switch

Switch is a native checkbox presented as an on/off toggle. It supports controlled and uncontrolled values, three sizes, active-state tones, icons, track text, validation, loading, and read-only interaction. Use SwitchGroup when several switches share a heading, description, validation message, or value collection.

Basic switchCopy Anchor Link

import { Switch } from '@mosmox/ui';

<Switch label="Notifications" />

The visible label is associated with the native checkbox through the wrapping label element. Native checkbox props such as name, value, required, id, form, aria-label, and aria-describedby are forwarded.

Controlled and uncontrolled valuesCopy Anchor Link

Use checked and onChange when the parent owns the value:

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

<Switch
  label="Auto-save"
  checked={enabled}
  onChange={(event) => setEnabled(event.target.checked)}
/>

Use defaultChecked when the switch should manage its own state:

<Switch label="Compact mode" defaultChecked />

onChange receives the native ChangeEvent<HTMLInputElement>. loading, disabled, and readOnly prevent a value change; when the switch is read-only, it remains focusable and its current value is still available to assistive technology.

Sizes, label position, and state contentCopy Anchor Link

<Switch label="Default" size="default" />
<Switch label="Small" size="sm" />
<Switch label="Extra small" size="xs" />
<Switch label="Label on the left" labelPosition="left" />
<Switch label="With state text" onLabel="On" offLabel="Off" />

The default label position is right. onLabel and offLabel add visible state text without changing the native boolean value.

onIcon and offIcon render inside the thumb. Keep icons decorative because the switch's accessible name comes from label or the native aria-label:

import { Check, X } from '@mosmox-ui/icons';

<Switch
  label="Sync enabled"
  defaultChecked
  onIcon={<Check size={11} />}
  offIcon={<X size={11} />}
/>

Active tones and statusCopy Anchor Link

tone controls the active track color and defaults to primary for backward compatibility. Available tones are primary, success, warning, and danger.

<Switch label="Primary" defaultChecked tone="primary" />
<Switch label="Saved" defaultChecked tone="success" />
<Switch label="Needs review" defaultChecked tone="warning" />
<Switch label="Destructive option" defaultChecked tone="danger" />

Use status="success" or status="warning" when the switch needs a semantic success or warning treatment independent of its active tone. An error always takes precedence over status for validation styling and aria-invalid.

<Switch label="Preference saved" status="success" defaultChecked />
<Switch label="Review required" status="warning" defaultChecked />
<Switch
  label="Save preference"
  status="warning"
  error="The preference could not be saved."
/>

Loading, disabled, and read-only statesCopy Anchor Link

Set loading while an asynchronous preference update is in progress. Loading disables interaction and shows a token-colored spinner inside the white thumb; on/off icons and track text are hidden while it is active. loadingLabel adds visible status text while loading; if omitted, the status is announced as Loading.

<Switch label="Saving preference" checked loading loadingLabel="Saving…" />
<Switch label="Unavailable preference" disabled />
<Switch label="Audited preference" readOnly defaultChecked />

Read-only switches are not disabled: they can receive focus and expose aria-readonly="true", but pointer and keyboard attempts do not change the value or call onChange.

Description and validationCopy Anchor Link

<Switch
  label="Share diagnostics"
  description="Only anonymous diagnostic data is collected."
  name="shareDiagnostics"
  required
/>

<Switch
  label="Accept terms"
  error="You must accept the terms to continue."
/>

Descriptions and errors are connected to the input through aria-describedby. An error also sets aria-invalid unless it is explicitly overridden with the native prop.

SwitchGroupCopy Anchor Link

SwitchGroup provides a shared label, description, and error and can manage a collection of switch values. Give each grouped switch a distinct value; the group value is an array of selected values.

import { Switch, SwitchGroup } from '@mosmox/ui';

const [channels, setChannels] = useState(['email']);

<SwitchGroup
  label="Notification channels"
  description="Choose where updates may be delivered."
  value={channels}
  onChange={(nextValue) => setChannels(nextValue)}
>
  <Switch label="Email" value="email" />
  <Switch label="Push notifications" value="push" />
  <Switch label="Weekly digest" value="digest" />
</SwitchGroup>

Use defaultValue for an uncontrolled group. onChange receives the next string[] followed by the native input event:

<SwitchGroup
  label="Workspace features"
  defaultValue={['comments']}
  onChange={(nextValue, event) => {
    console.log(nextValue, event.target.value);
  }}
>
  <Switch label="Comments" value="comments" />
  <Switch label="Mentions" value="mentions" />
</SwitchGroup>

Group-level disabled and readOnly apply to all child switches. The group uses a native fieldset and legend; its description and error IDs are also included in each child switch's accessible description.

Accessibility and behaviorCopy Anchor Link

• Switch preserves native checkbox semantics and Space-key interaction;
• the wrapping label associates visible text with the checkbox;
• controlled switches render the checked prop and notify changes through onChange;
• uncontrolled switches initialize from defaultChecked and update internally;
• descriptions, errors, and group messages are announced through aria-describedby;
• loading and disabled switches are disabled native inputs;
• read-only switches remain focusable, expose aria-readonly, and do not change or emit onChange;
• status styling is suppressed when error is present so validation remains unambiguous;
• icon and track content is decorative and must not be the only accessible name.

Theme tokensCopy Anchor Link

Switches use shared theme tokens for text, surface, control border, focus, typography, and active tones:

Override these tokens globally or with ConfigProvider theme colors:

<ConfigProvider
  theme={{
    colors: {
      primary: '#14532d',
      success: '#16a34a',
      warning: '#d97706',
      warningText: '#b45309',
      danger: '#dc2626',
    },
  }}
>
  <Switch label="Custom theme" defaultChecked tone="success" />
</ConfigProvider>

API ReferenceCopy Anchor Link

SwitchCopy Anchor Link

Switch also accepts supported native InputHTMLAttributes<HTMLInputElement> props. The type and size attributes are owned by the component.

SwitchGroupCopy Anchor Link