Switch

Overview

The Switch component provides a toggle for a single on/off setting that takes effect immediately. It is built on the Radix UI Switch primitive with design-system styling, and can be paired with an optional label and caption.

Installation

import { Switch } from "@harnessio/ui/components";

// Controlled
<Switch
  id="airplane-mode"
  checked={airplaneModeEnabled}
  onCheckedChange={setAirplaneModeEnabled}
  label="Airplane mode"
  caption="Enable or disable airplane mode to control all wireless communication."
/>

// Uncontrolled — set the initial state with defaultChecked
<Switch id="notifications" defaultChecked label="Enable notifications" />

Usage

Anatomy

Switch renders a toggle control with an optional label block beside it.

• The toggle itself is a role="switch" button with a sliding thumb; its data-state reflects checked or unchecked.
• When you pass a label and/or caption, they render in a block next to the toggle: the label above and the caption (secondary text) below.
• The component holds no state of its own — pass checked + onCheckedChange to control it, or defaultChecked to run it uncontrolled.
• Every switch needs an id. If you omit it, one is generated automatically and used to associate the label with the toggle (clicking the label toggles the switch).

Caution

showOptionalLabel has inverted semantics: leave it unset (or true) and the field is treated as optional with no marker. Pass showOptionalLabel={false} to mark the field as required, which renders a * next to the label. There is no “(optional)” text — the prop only controls the required asterisk.

Best practices

Do

• Use a switch for a setting that applies immediately, with no separate save step.
• Give every switch a clear label (or an aria-label when there’s no visible text) so its purpose is obvious.
• Keep captions short and phrase the label as the “on” state (“Enable notifications”) so the toggle direction is unambiguous.

Don’t

• Don’t use a switch where a submit action is required to apply the change — use a checkbox in a form instead.
• Don’t rely on the caption to carry the switch’s meaning; the label alone should say what it toggles.

Content

• Write labels as a positive statement of what turning the switch on does.
• Reserve the caption for a brief clarification, not for restating the label.

Accessibility

Keyboard

• The switch is focusable and toggles with Space (and Enter), following the underlying Radix button behavior.

Labeling

• A visible label is associated with the toggle through the shared id, so clicking the label text toggles the switch and screen readers announce it.
• When there’s no visible label, pass an aria-label so the control still has an accessible name.
• captionTooltip sets a native title attribute on the caption for hover text; it is not a design-system tooltip.

Focus & states

• disabled disables the toggle and suppresses onCheckedChange.
• The role="switch" and on/off state (data-state) are provided by the primitive, so assistive tech announces the current state.

Properties

Properties

Prop	Required	Default	Type
checked	false		boolean
defaultChecked	false		boolean
onCheckedChange	false		(checked: boolean) => void
disabled	false	false	boolean
label	false		string
caption	false		string
showOptionalLabel	false	true	boolean
captionTooltip	false		string
id	false		string
className	false		string

Note

Switch also accepts the standard Radix Switch props (such as name and value). Note it does not accept a required prop — use showOptionalLabel= {false} to show the required marker.