Available from v1.12.0
Switch
Switch is a themed UISwitch subclass with custom off tint color and dynamic thumb colors for on/off states.
Platform availability: iOS 17.0+
When to use:
- Use Switch for binary settings that take effect immediately, such as enabling notifications or toggling features on/off.
- Consider using Checkbox when the setting is part of a form that requires explicit submission, or when multiple options can be selected.
Features:
- Custom off tint color support.
- Dynamic thumb tint colors for on and off states.
- Value change callback.
- Built-in accessibility support.
Import
import BackbaseDesignSystem
Visual reference
|
|
|
|
API reference
Switch
A themed UISwitch subclass with custom styling support.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
isOnValueChanged |
((Bool) -> Void)? |
The isOnValueChanged callback executed when isOn value changes. |
|
offTintColor |
UIColor? |
The offTintColor used when the switch is in the off position. |
|
dynamicThumbTintColor |
DynamicThumbTintColor? |
The dynamicThumbTintColor for different on and off states. |
|
isOn |
Bool |
The isOn current on/off state of the switch. |
Initializers
- init(style:) Initializes a Switch object with the given styling.
|
Parameter |
Type |
Description |
|---|---|---|
|
style |
SwitchStyle |
A style block for styling. Defaults to DesignSystem.shared.styles.switchStyle. |
DynamicThumbTintColor
A struct representing different colors for the switch's on and off states.
|
Property |
Type |
Description |
|---|---|---|
|
whileOn |
UIColor |
The whileOn color for the on state. |
|
whileOff |
UIColor |
The whileOff color for the off state. |
Configuration
|
Parameter |
Type |
Default |
|---|---|---|
|
style |
SwitchStyle |
DesignSystem.shared.styles.switchStyle |
style
The style parameter applies visual styling to the switch using a Style closure.
let toggle = Switch()
toggle.isOnValueChanged = { isOn in
print("Switch is now: \(isOn ? "on" : "off")")
}
Usage
Basic usage
Create a switch with default styling:
let toggle = Switch()
toggle.isOnValueChanged = { isOn in
print("Switch is now: \(isOn ? "on" : "off")")
}
Custom styling
Apply custom styling to the switch:
let style: Style<Switch> = { swtch in
swtch.onTintColor = .systemTeal
swtch.offTintColor = .systemRed
swtch.dynamicThumbTintColor = .init(whileOn: .systemRed, whileOff: .systemYellow)
}
let toggle = Switch(style: style)
Observing value changes
React to switch value changes:
let toggle = Switch()
toggle.isOnValueChanged = { isOn in
if isOn {
// Handle on state
} else {
// Handle off state
}
}
States and variants
Toggle states
|
State |
Property |
Description |
|---|---|---|
|
On |
isOn = true |
Switch is in the on position |
|
Off |
isOn = false |
Switch is in the off position |
Visual states
|
State |
Property |
Description |
|---|---|---|
|
Enabled |
isEnabled = true |
Default interactive state |
|
Disabled |
isEnabled = false |
Non-interactive state with dimmed appearance |
// Set on state
toggle.isOn = true
// Disable the switch
toggle.isEnabled = false
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.switchStyle |
Default switch style. |
Custom styles
Create and apply custom switch styles:
let customStyle: Style<Switch> = { swtch in
swtch.onTintColor = Theme.colors.primary.default
swtch.offTintColor = Theme.colors.background.support
swtch.dynamicThumbTintColor = Switch.DynamicThumbTintColor(
whileOn: .white,
whileOff: Theme.colors.foreground.support
)
}
let toggle = Switch(style: customStyle)
Modifying global style
DesignSystem.shared.styles.switchStyle = { swtch in
swtch.onTintColor = .systemGreen
swtch.offTintColor = .systemGray
}
Events
|
Event |
Type |
Description |
|---|---|---|
|
isOnValueChanged |
((Bool) -> Void)? |
Called when the switch value changes. |
Accessibility
The Switch component has built-in accessibility support with customizable labels.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
Identifies the control as a switch |
String? |
|
accessibilityValue |
Announces the current on/off state |
String? |
Best practices
- The switch automatically sets appropriate accessibility traits
- On/off states are announced to screen readers
- Use descriptive labels that explain what the switch controls
Localizable strings
Override these strings to customize accessibility text:
"DesignSystem.switch.accessibility.title" = "Switch";
"DesignSystem.switch.accessibility.on" = "On";
"DesignSystem.switch.accessibility.off" = "Off";
Dependencies
- External dependencies: None
- Internal dependencies: None
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses semantic tokens only. See Semantic tokens below.
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.foreground.brand |
On state tint color |
|
Colors |
Theme.colors.background.support |
Off state tint color |
|
Colors |
Theme.colors.foreground.support |
Off state thumb color |
|
Styles |
DesignSystem.shared.styles.switchStyle |
Default switch style |