Toggle
Turns a setting on or off with an immediately applied change.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import { GlToggle } from "gitlab-ui-react/toggle";<GlToggle label="Email notifications" />Default
Use a toggle for a binary setting that takes effect immediately. Use a checkbox when the value is submitted with other form fields as one grouped action.
Toggle with supporting text
Email notificationsControls whether notifications are sent for new activity.You can change this setting at any time.
import { GlToggle } from "gitlab-ui-react/toggle";
export default function ToggleExample() {
return (
<GlToggle
defaultValue
description="Controls whether notifications are sent for new activity."
help="You can change this setting at any time."
label="Email notifications" />
);
}
States
The component supports controlled and uncontrolled values, disabled presentation, and a loading state that prevents activation while an update is pending.
Toggle states
On
Off
On disabled
Off disabled
Loading on
Loading off
import { GlToggle } from "gitlab-ui-react/toggle";
export default function ToggleStatesExample() {
return (
<div className="flex flex-col items-start gap-5">
<GlToggle defaultValue label="On" />
<GlToggle label="Off" />
<GlToggle disabled label="On disabled" value />
<GlToggle disabled label="Off disabled" />
<GlToggle label="Loading on" loading value />
<GlToggle label="Loading off" loading />
</div>
);
}
Label positions
Use the default top position when description or help text is needed. The left position creates a compact inline layout, while hidden keeps the accessible label available to assistive technology.
Toggle label positions
Top label
Left label
Hidden label
import { GlToggle } from "gitlab-ui-react/toggle";
export default function ToggleLabelPositionsExample() {
return (
<div className="flex flex-col items-start gap-6">
<GlToggle defaultValue label="Top label" />
<GlToggle defaultValue label="Left label" labelPosition="left" />
<GlToggle aria-label="Hidden label" label="Hidden label" labelPosition="hidden" />
</div>
);
}
Accessibility
- Always provide a concise
label, even whenlabelPosition="hidden". - Write the label as the setting being controlled, not as an instruction such as “Turn on”.
- Use
descriptionfor context andhelpfor supporting guidance. Both are shown only in vertical layouts. - Do not switch the controlled value until an asynchronous update succeeds; use
loadingwhile waiting.
API
| Prop | Description | Default |
|---|---|---|
label |
Sets the visible and accessible switch label. | — |
defaultValue |
Sets the initial uncontrolled value. | false |
value |
Controls the current value. | — |
onValueChange |
Reports the next value after activation. | — |
labelPosition |
Places the label at top, left, or visually hidden. |
"top" |
description |
Adds description text in vertical layouts. | — |
help |
Adds help text linked through aria-describedby. |
— |
disabled |
Disables the switch. | false |
loading |
Shows a spinner and prevents activation. | false |
name |
Adds a hidden input carrying the current boolean value. | — |
wrapperProps |
Applies attributes to the outer layout element. | — |