Available from v8.0.0
BB.RadioButton
BB.RadioButton is a customizable radio button component for creating accessible and visually appealing radio button groups.
Platform availability: iOS 17.0+
When to use:
- Use BB.RadioButton when users must select exactly one option from a list of mutually exclusive choices.
- Consider BB.SegmentedControl when there are 2–5 options that fit well in a horizontal layout.
Import
import SwiftUI
import BackbaseDesignSystem
Visual reference
|
|
|
|
API reference
BB.RadioButton
Typealias
- RadioButtonAccessibilityLabelConfig: A type alias for a closure that generates an accessibility label string based on the radio button's state.
|
Parameter |
Type |
Description |
|---|---|---|
|
isSelected |
Bool |
The isSelected indicates if the option is selected |
|
hasError |
Bool |
The hasError indicates if the radio button has an error |
Returns: String - The accessibility label.
Initializers
init(options:selected:)
Initializes a radio button with given options.
|
Parameter |
Type |
Description |
|---|---|---|
|
options |
[String] |
The options array of strings representing the radio button options |
|
selected |
Binding<String?> |
The selected binding to the string that represents the selected option |
Methods
iconAlignment(_:)
Sets the vertical alignment for the radio button icon.
|
Parameter |
Type |
Description |
|---|---|---|
|
iconAlignment |
VerticalAlignment |
The iconAlignment specifies the vertical alignment for the icon |
Returns: Self - A modified version of the radio button with specified icon alignment.
hasError(_:)
Sets the error state for the radio button.
|
Parameter |
Type |
Description |
|---|---|---|
|
hasError |
Bool |
The hasError indicates if the radio button should display an error state |
Returns: Self - A modified version of the radio button with the error state set.
hasError(_:) (Binding)
Sets the error state for the radio button using a Binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
hasError |
Binding<Bool> |
The hasError binding indicating if the radio button should display an error state |
Returns: Self - A modified version of the radio button with the error state set.
customImage(selectedImage:backgroundImage:)
Customizes the images used for the radio button's selected and background states.
|
Parameter |
Type |
Description |
|---|---|---|
|
selectedImage |
UIImage |
The selectedImage to display when the radio button is selected |
|
backgroundImage |
UIImage |
The backgroundImage to display as the radio button background |
Returns: Self - A modified version of the radio button with the specified images.
customAccessibilityLabelConfiguration(_:)
Sets up a custom accessibility label configuration for the radio button.
|
Parameter |
Type |
Description |
|---|---|---|
|
configuration |
RadioButtonAccessibilityLabelConfig |
The configuration closure that generates accessibility labels |
Returns: Self - A modified version of the radio button with the specified accessibility configurator.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
options |
[String] |
— |
|
selected |
Binding<String?> |
— |
|
iconAlignment |
VerticalAlignment |
.center |
|
hasError |
Bool |
false |
options
The options property defines the list of selectable options displayed in the radio button group. Each option is represented as a string.
BB.RadioButton(options: ["Option 1", "Option 2", "Option 3"], selected: $selectedOption)
selected
The selected property is a binding that tracks which option is currently selected. Set to nil for no selection.
@State private var selectedOption: String? = "Option 1"
BB.RadioButton(options: ["Option 1", "Option 2"], selected: $selectedOption)
iconAlignment
The iconAlignment property determines the vertical alignment of the radio button icon relative to the label text.
BB.RadioButton(options: ["Option 1", "Option 2"], selected: $selectedOption)
.iconAlignment(.top)
hasError
The hasError property indicates whether the radio button group should display an error state.
BB.RadioButton(options: ["Option 1", "Option 2"], selected: $selectedOption)
.hasError(true)
Usage
Basic usage
Create a simple radio button group with options.
import SwiftUI
struct ContentView: View {
@State private var selectedOption: String? = ""
var body: some View {
BB.RadioButton(options: ["Option 1", "Option 2", "Option 3"], selected: $selectedOption)
}
}
Common use cases
With error state
Display the radio button in an error state.
@State private var selectedOption: String? = ""
@State private var showError: Bool = true
var body: some View {
BB.RadioButton(options: ["Option 1", "Option 2", "Option 3"], selected: $selectedOption)
.hasError($showError)
}
With custom images and accessibility
Customize the appearance and accessibility configuration.
@State private var selectedOption: String? = ""
@State private var showError: Bool = false
var body: some View {
BB.RadioButton(options: ["Option 1", "Option 2", "Option 3"], selected: $selectedOption)
.iconAlignment(.center)
.hasError($showError)
.customImage()
.customAccessibilityLabelConfiguration { isSelected, hasError in
"Radio button is " + (isSelected ? "selected" : "unselected") + (hasError ? ", with error" : "")
}
}
States and variants
Unselected state
The default state when no option is selected.
Visual characteristics:
- Empty circle icon
- Default foreground color
BB.RadioButton(options: ["Option 1", "Option 2"], selected: .constant(nil))
Selected state
An option is selected and visually highlighted.
Visual characteristics:
- Filled circle icon with brand color
- Selected option label
BB.RadioButton(options: ["Option 1", "Option 2"], selected: .constant("Option 1"))
Error state
The radio button group displays an error indication.
Visual characteristics:
- Error color applied to icon and border
- Visual feedback for validation failure
BB.RadioButton(options: ["Option 1", "Option 2"], selected: $selectedOption)
.hasError(true)
Customization
Styling
The BB.RadioButton component uses the design system's radio button styling tokens. Customization is applied through the theming infrastructure.
Custom images
Use custom images for the selected and background states.
BB.RadioButton(options: ["Option 1", "Option 2"], selected: $selectedOption)
.customImage(
selectedImage: UIImage(named: "customSelected")!,
backgroundImage: UIImage(named: "customBackground")!
)
Custom styles
To customize radio button appearance, modify the theme tokens in your custom JSON theme file and load it using Theme.switchTo():
Theme.switchTo("customTokens")
Accessibility
This component can be configured with accessibility features at the integration level. Use the standard SwiftUI accessibility modifiers to ensure a fully accessible experience for all users.
Accessibility configuration
|
Modifier |
Description |
|---|---|
|
.accessibilityLabel(_:) |
Sets the accessibility label for screen readers |
|
.accessibilityHint(_:) |
Provides additional context for the action |
|
.accessibilityValue(_:) |
Sets the current value for the element |
Best practices
- Provide meaningful accessibility labels that describe the element's purpose.
- Use accessibility hints to provide additional context when needed.
- Ensure all interactive elements are accessible.
BB.RadioButton()
.accessibilityLabel("Descriptive label")
.accessibilityHint("Additional context")
Dependencies
- External dependencies: None
- Internal dependencies: BackbaseDesignSystem
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 |
|---|---|---|
|
Selected color |
Theme.colors.foreground.brand |
Brand color for the selected radio button icon |
|
Unselected color |
Theme.colors.foreground.default |
Default color for the unselected radio button icon |
|
Error color |
Theme.colors.foreground.negative |
Error color when radio button is in error state |
|
Text color |
Theme.colors.foreground.default |
Text color for option labels |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.radioButton.accessibility.checkbox |
"%@, radio button" |
Accessibility label format for radio button |
|
DesignSystem.radioButton.accessibility.error |
"%@, showing error" |
Accessibility label format when error is present |
|
DesignSystem.radioButton.accessibility.selected |
"%@, selected" |
Accessibility label format when selected |
|
DesignSystem.radioButton.accessibility.unselected |
"%@, unselected" |
Accessibility label format when unselected |
To customize these strings, add the keys to your app's Localizable.strings file.
See also
- BB.SegmentedControl - For single selection from a small set of options
- BB.Button - For action buttons