Switch

A controlled switch for boolean settings.

Examples

Default

NotificationsReceive product updates and account alerts.

<SwitchStory {...args} />

States

Off

On

Disabled

Loading

Disabled loading

Loading

Loading off

Loading

Loading

<VStack gap={4}>
  <Switch isSelected={false} label="Off" onChange={() => {}} />
  <Switch isSelected label="On" onChange={() => {}} />
  <Switch
    isDisabled
    isSelected={false}
    label="Disabled"
    onChange={() => {}}
  />
  <Switch
    isDisabled
    isLoading
    isSelected
    label="Disabled loading"
    onChange={() => {}}
  />
  <Switch
    isLoading
    isSelected={false}
    label="Loading off"
    onChange={() => {}}
  />
  <Switch isLoading isSelected label="Loading" onChange={() => {}} />
</VStack>

Error

NotificationsReceive product updates and account alerts.

This setting is required.

<SwitchStory {...args} />

Label Start

Sync automaticallyReceive product updates and account alerts.

<SwitchStory {...args} />

Spread

Require approvalReceive product updates and account alerts.

<SwitchStory {...args} />

Hidden Label

Enable notifications

<SwitchStory {...args} />

Label Icon

Security alertsReceive product updates and account alerts.

<SwitchStory {...args} />

Label Tooltip

Marketing emails

Used for product announcements and lifecycle emails.

Receive product updates and account alerts.

<SwitchStory {...args} />

Necessity

Required setting · Required

Optional setting · Optional

<VStack gap={4}>
  <Switch
    isRequired
    isSelected
    label="Required setting"
    onChange={() => {}}
  />
  <Switch
    isOptional
    isSelected={false}
    label="Optional setting"
    onChange={() => {}}
  />
</VStack>

Description

Compact setting

Detailed settingThis longer description explains when the setting applies and wraps onto multiple lines in constrained layouts.

<VStack gap={4}>
  <Switch isSelected label="Compact setting" onChange={() => {}} />
  <Switch
    description="This longer description explains when the setting applies and wraps onto multiple lines in constrained layouts."
    isSelected
    label="Detailed setting"
    onChange={() => {}}
    style={{maxWidth: 360}}
  />
</VStack>

Warning

NotificationsReceive product updates and account alerts.

Notification delivery may be delayed.

<SwitchStory {...args} />

Success

NotificationsReceive product updates and account alerts.

This setting is active and healthy.

<SwitchStory {...args} />

API

Switch

A controlled switch for boolean settings.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the checkbox input.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether the switch is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the switch is loading.
isSelected*	boolean	—	Whether the switch is on.
label*	string	—	Switch label.
labelIcon	IconComponent	—	Content rendered before the label.
labelPosition	"end" | "start"	'end'	Which side of the switch the label appears on.
labelSpacing	"default" | "spread"	'default'	Spacing behavior between label and switch.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch receives focus.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the checkbox input.
status	InputStatus	—	Validation status displayed below the switch.
style	CSSProperties	—	Inline styles applied to the field root.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the checkbox input.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether the switch is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the switch is loading.
isSelected*	boolean	—	Whether the switch is on.
label*	string	—	Switch label.
labelIcon	IconComponent	—	Content rendered before the label.
labelPosition	"end" | "start"	'end'	Which side of the switch the label appears on.
labelSpacing	"default" | "spread"	'default'	Spacing behavior between label and switch.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch receives focus.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the checkbox input.
status	InputStatus	—	Validation status displayed below the switch.
style	CSSProperties	—	Inline styles applied to the field root.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the checkbox input.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether the switch is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the switch is loading.
isSelected*	boolean	—	Whether the switch is on.
label*	string	—	Switch label.
labelIcon	IconComponent	—	Content rendered before the label.
labelPosition	"end" | "start"	'end'	Which side of the switch the label appears on.
labelSpacing	"default" | "spread"	'default'	Spacing behavior between label and switch.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the switch receives focus.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the checkbox input.
status	InputStatus	—	Validation status displayed below the switch.
style	CSSProperties	—	Inline styles applied to the field root.
isOptional	false	—
isRequired*	true	—