import {ToggleSwitch} from '@primer/react-brand'Examples
Default
Uncontrolled
defaultChecked sets the initial value. onChange receives the next boolean value, not a native change event.
Controlled
Sizes
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.
Disabled
Without FormControl
Visually hidden label with FormControl
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
| Name | Type | Default | Description |
|---|---|---|---|
checked | boolean | Controlled on/off value. | |
defaultChecked | boolean | false | Initial uncontrolled value. |
onChange | (checked: boolean) => void | Called once per accepted activation with the next value. | |
onClick | React.MouseEventHandler<HTMLButtonElement> | Activation callback receiving the button event. | |
disabled | boolean | false | Blocks activation while retaining keyboard focusability. |
loading | boolean | false | Displays pending feedback and exposes aria-busy without blocking interaction. |
size | 'small' | 'medium' | 'medium' | Alternative sizes. |
loadingLabel | string | 'Loading' | Localized loading announcement. |
loadingLabelDelay | number | 2000 | Announcement delay in milliseconds. |
spinnerPosition | 'start' | 'end' | 'end' | Indicator placement beside the switch when no visible FormControl label is available. |
hasStatusLabel | boolean | false | Shows 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 / Off | Visible status text for each state. Custom text describes the switch when shown. |
aria-label | string | Explicit accessible name matching equivalent visible labeling. | |
aria-labelledby | string | IDs of visible labeling elements. | |
aria-describedby | string | Description IDs, combined with status, FormControl, and loading descriptions. | |
aria-invalid | React ARIA attribute | Validation state of the switch button. | |
ref | React.Ref<HTMLButtonElement> | Ref for the focusable button. | |
className | string | Class applied to the component wrapper. | |
data-testid | string | Test ID applied to the component wrapper. |
Other standard button attributes, including aria-controls, tabIndex, keyboard handlers, and style, apply to the switch button.