Available from v8.1.0
BB.Switch
BB.Switch is a SwiftUI binary toggle component with design-system styling.
Platform availability: iOS 17.0+
- Supports binding-based state updates.
- Supports custom on and off track colors.
- Supports dynamic thumb colors per state.
When to use:
- Use BB.Switch for explicit on and off selections.
Import
BackbaseDesignSystem
import SwiftUI
import BackbaseDesignSystem
Visual reference
|
|
|
|
API reference
BB.Switch
Initializers
init(isOn:onValueChanged:)
Creates a switch with state binding and optional change callback.
|
Parameter |
Type |
Description |
|---|---|---|
|
isOn |
Binding<Bool> |
Binding to the switch state |
|
onValueChanged |
((Bool) -> Void)? |
Optional closure called when value changes |
Methods
dynamicThumbTintColor(_ colors: DynamicThumbTintColor?)
Sets custom colors for the switch thumb in on and off states.
|
Parameter |
Type |
Description |
|---|---|---|
|
colors |
DynamicThumbTintColor? |
Thumb color configuration |
Returns: Self - Modified switch instance.
offTintColor(_ color: UIColor)
Sets the color for the switch background when off.
|
Parameter |
Type |
Description |
|---|---|---|
|
color |
UIColor |
The color to use when off |
Returns: Self - Modified switch instance.
onTintColor(_ color: UIColor)
Sets the color for the switch background when on.
|
Parameter |
Type |
Description |
|---|---|---|
|
color |
UIColor |
The color to use when on |
Returns: Self - Modified switch instance.
Nested types
DynamicThumbTintColor
Defines custom colors for the switch thumb when it's on and off.
|
Property |
Type |
Description |
|---|---|---|
|
whileOff |
UIColor |
Thumb color in the off state |
|
whileOn |
UIColor |
Thumb color in the on state |
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
isOn |
Binding<Bool> |
Required |
|
onValueChanged |
((Bool) -> Void)? |
nil |
isOn
The isOn property tracks the current switch value via a binding.
@State private var isOn = false
BB.Switch(isOn: $isOn)
onValueChanged
The onValueChanged property receives updates when the switch value changes.
BB.Switch(isOn: $isOn, onValueChanged: { newValue in
print("Switch changed to: \(newValue)")
})
Usage
Basic usage
import SwiftUI
import BackbaseDesignSystem
struct ContentView: View {
@State private var isOn = false
var body: some View {
BB.Switch(isOn: $isOn)
}
}
Common use cases
Value callback
React to value changes with a callback closure.
BB.Switch(isOn: $isOn, onValueChanged: { value in
print("Changed: \(value)")
})
Custom track colors
Customize the on and off background colors.
BB.Switch(isOn: $isOn)
.onTintColor(.systemGreen)
.offTintColor(.systemGray4)
Custom thumb colors
Set different thumb colors for on and off states.
BB.Switch(isOn: $isOn)
.dynamicThumbTintColor(
BB.Switch.DynamicThumbTintColor(whileOn: .white, whileOff: .lightGray)
)
Disabled state
Disable the switch using the SwiftUI environment.
BB.Switch(isOn: $isOn)
.disabled(true)
States and variants
On
This state occurs when isOn is true.
Visual characteristics:
- On-state track color (brand color by default)
- On accessibility value
@State private var isOn = true
BB.Switch(isOn: $isOn)
Off
This state occurs when isOn is false.
Visual characteristics:
- Off-state track color (neutral color by default)
- Off accessibility value
@State private var isOn = false
BB.Switch(isOn: $isOn)
Disabled
This state occurs when .disabled(true) is applied.
Visual characteristics:
- Reduced opacity style (50%)
- No interaction
BB.Switch(isOn: $isOn)
.disabled(true)
Customization
Styling
|
Visual reference |
API |
Description |
|---|---|---|
|
|
onTintColor(_:), offTintColor(_:), dynamicThumbTintColor(_:) |
Switch color customization |
Custom styles
BB.Switch(isOn: $isOn)
.onTintColor(.systemGreen)
.offTintColor(.systemGray4)
.dynamicThumbTintColor(
BB.Switch.DynamicThumbTintColor(whileOn: .white, whileOff: .lightGray)
)
Error handling
BB.Switch does not throw errors in its public API.
Events
|
Event |
Type |
Description |
|---|---|---|
|
onValueChanged |
(Bool) -> Void |
Called when switch value changes |
Accessibility
This component has built-in accessibility support with localized labels and values.
Accessibility configuration
|
Modifier |
Description |
|---|---|
|
.accessibilityLabel(_:) |
Overrides the default switch label |
|
.accessibilityHint(_:) |
Sets hint text |
|
.accessibilityValue(_:) |
Overrides the on/off value text |
Built-in accessibility
The switch automatically sets:
- Accessibility label: Localized "Switch" string
- Accessibility value: Localized "On" or "Off" based on state
Best practices
- Use the built-in accessibility labels when possible.
- Override accessibility labels only when additional context is needed.
- Ensure the switch's purpose is clear from surrounding context.
BB.Switch(isOn: $isOn)
.accessibilityLabel("Dark mode")
.accessibilityHint("Double tap to toggle dark mode")
Dependencies
- External dependencies:
- None: No third-party package dependency for the public API.
- Framework requirements: SwiftUI, UIKit.
- Internal dependencies:
- BackbaseDesignSystem: Theme colors and localized accessibility strings.
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by Switch:
- color/switch: Background and thumb colors per state
Switch tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Off Background |
theme.color.switch.off.background |
{theme.color.background.neutral} |
|
On Background |
theme.color.switch.on.background |
{theme.color.background.brand} |
|
Thumb Off |
theme.color.switch.off.thumb |
{theme.color.on-background.brand} |
|
Thumb On |
theme.color.switch.on.thumb |
{theme.color.on-background.brand} |
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.background.brand |
On-state track color |
|
Colors |
Theme.colors.background.neutral |
Off-state track color |
|
Colors |
Theme.colors.foreground.onColor |
Thumb color |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.switch.accessibility.off |
Off |
Accessibility off value |
|
DesignSystem.switch.accessibility.on |
On |
Accessibility on value |
|
DesignSystem.switch.accessibility.title |
Switch |
Accessibility label |
To customize these strings, add the keys to your app's Localizable.strings file.
Known limitations
- iOS 26 feature-flag path uses native rendering and applies only on-tint customization.
- Disabled state reduces opacity to 50%.
See also
- BB.SegmentedControl - Single selection control
- BB.Checkbox - Multi-selection control