ToggleSwitch

Use a toggle switch for a boolean setting that takes effect immediately.

import {ToggleSwitch} from '@primer/react-brand'

Examples

Default

Loading

Uncontrolled

defaultChecked sets the initial value. onChange receives the next boolean value, not a native change event.

Loading

Controlled

Loading

Sizes

Loading

Status label

Enable hasStatusLabel when space permits to make the current state easier to understand. The text appears before the track by default. Use statusLabelPosition to move it after the track, and labels to localize or reword it. The status text increases the control width.

Custom status text supplements the setting label; it does not replace it. The switch exposes its state as on or off to assistive technology, so the setting label must make sense with on and off. For example, use “Make repository public” rather than “Repository visibility” with “Public” and “Private” status text.

Loading

Disabled

Loading

Without FormControl

Loading

Visually hidden label with FormControl

Loading

Accessibility

ToggleSwitch exposes its state with role="switch" and aria-checked. Give it a descriptive setting label with FormControl.Label or aria-labelledby. The label describes the setting; status text does not replace it or change the switch’s accessible name. The thumb position also communicates state, beyond color.

Enable hasStatusLabel when space permits. The visible On/Off text is part of the switch’s click target and stays visible in both sizes, light and dark modes, and forced-colors mode. Default On/Off text is hidden from assistive technology because aria-checked already exposes the state. With hasStatusLabel, custom labels.on and labels.off text becomes the accessible description. Immediate activation changes politely announce custom text; later controlled updates change the description without an announcement. Translated labels can repeat the state. Both labels reserve the same width to prevent layout shifts. In narrow containers, FormControl places the setting label above the switch so longer labels can wrap without horizontal scrolling.

The default track border and enabled thumb each meet 3:1 contrast against adjacent colors in light and dark modes. ToggleSwitch uses existing Brand palette colors. Recheck contrast if you override its colors or place it on a custom background.

Component Props

NameTypeDefaultDescription
checkedbooleanControlled on/off value.
defaultCheckedbooleanfalseInitial uncontrolled value.
onChange(checked: boolean) => voidCalled once per accepted activation with the next value.
onClickReact.MouseEventHandler<HTMLButtonElement>Activation callback receiving the button event.
disabledbooleanfalseBlocks activation while retaining keyboard focusability.
loadingbooleanfalseDisplays pending feedback and exposes aria-busy without blocking interaction.
size'small' | 'medium''medium'Alternative sizes.
loadingLabelstring'Loading'Localized loading announcement.
loadingLabelDelaynumber2000Announcement delay in milliseconds.
spinnerPosition'start' | 'end''end'Indicator placement beside the switch when no visible FormControl label is available.
hasStatusLabelbooleanfalseShows visible On/Off status text beside the track.
statusLabelPosition'start' | 'end''start'Status text placement relative to the track.
labels{on?: string; off?: string}On / OffVisible status text for each state. Custom text describes the switch when shown.
aria-labelstringExplicit accessible name matching equivalent visible labeling.
aria-labelledbystringIDs of visible labeling elements.
aria-describedbystringDescription IDs, combined with status, FormControl, and loading descriptions.
aria-invalidReact ARIA attributeValidation state of the switch button.
refReact.Ref<HTMLButtonElement>Ref for the focusable button.
classNamestringClass applied to the component wrapper.
data-testidstringTest ID applied to the component wrapper.

Other standard button attributes, including aria-controls, tabIndex, keyboard handlers, and style, apply to the switch button.