Available from v1.3.0
Checkbox
Checkbox is a themed replacement for UIButton styled as a checkbox with normal, selected, indeterminate, and error states.
Platform availability: iOS 17.0+
When to use:
- Use Checkbox when users need to select one or more options from a list, or to accept terms and conditions.
- Consider using Switch for binary on/off settings, or ChipView for compact filter selections.
Features:
- Normal, selected, and indeterminate states.
- Error state styling.
- Customizable checkbox images.
- Configurable icon alignment (center or top).
- Multi-line label support with character wrapping.
- Selection change callback.
Import
import BackbaseDesignSystem
Visual reference
|
|
|
|
|
|
|
|
API reference
Checkbox
A UIButton subclass styled as a checkbox with multiple states.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
indeterminate |
Bool |
The indeterminate state of the checkbox. Default is false. |
|
hasError |
Bool |
The hasError state indicating error styling. Default is false. |
|
isEnabled |
Bool |
The isEnabled state of the checkbox. |
|
isSelected |
Bool |
The isSelected state of the checkbox. |
|
lineBreakMode |
NSLineBreakMode |
The lineBreakMode for the label. Default is .byCharWrapping. |
|
iconAlignment |
IconAlignment |
The iconAlignment of the checkbox icon. Default is .center. |
|
normalImageTintColor |
UIColor |
The normalImageTintColor in normal state. |
|
disabledImageTintColor |
UIColor |
The disabledImageTintColor in disabled state. |
|
errorImageTintColor |
UIColor |
The errorImageTintColor in error state. |
|
selectionChanged |
((Bool) -> Void)? |
The selectionChanged callback when selection changes. |
|
accessibilityLabelConfigurator |
(Bool, Checkbox) -> Void |
The accessibilityLabelConfigurator for state-based accessibility labels. |
Initializers
- init() Creates a basic checkbox.
- init(_:_:)
|
Parameter |
Type |
Description |
|---|---|---|
|
title |
String |
The checkbox label text. |
|
style |
Style<Checkbox> |
The checkbox style. Default is DesignSystem.shared.styles.checkbox. |
Methods
setCustomBackgroundImage(normal:selected:) Sets custom images for the checkbox.
|
Parameter |
Type |
Description |
|---|---|---|
|
normal |
UIImage? |
The image for normal state. |
|
selected |
UIImage? |
The image for selected state. |
Checkbox.IconAlignment
|
Case |
Description |
|---|---|
|
.center |
Icon aligned to center of the label. |
|
.top |
Icon aligned to top of the label. |
Configuration
|
Parameter |
Type |
Default |
|---|---|---|
|
title |
String |
Required |
|
style |
Style<Checkbox> |
DesignSystem.shared.styles.checkbox |
title
The title parameter sets the text label displayed next to the checkbox.
let checkbox = Checkbox("Accept terms and conditions")
style
The style parameter applies visual styling to the checkbox using a Style closure.
let customStyle: Style<Checkbox> = { checkbox in
checkbox.normalImageTintColor = .systemBlue
}
let checkbox = Checkbox("Custom styled", customStyle)
Usage
Basic usage
let checkbox = Checkbox("Accept terms and conditions")
With custom style
let checkbox = Checkbox(
"Remember me",
DesignSystem.shared.styles.checkbox
)
Handling selection changes
let checkbox = Checkbox("Subscribe to newsletter")
checkbox.selectionChanged = { isSelected in
print("Checkbox is now: \(isSelected ? "selected" : "unselected")")
}
Indeterminate state
let checkbox = Checkbox("Select all")
checkbox.indeterminate = true
Error state
let checkbox = Checkbox("Required field")
checkbox.hasError = true
Custom images
let checkbox = Checkbox("Custom checkbox")
checkbox.setCustomBackgroundImage(
normal: UIImage(named: "unchecked"),
selected: UIImage(named: "checked")
)
Icon alignment for multi-line labels
let checkbox = Checkbox("This is a very long checkbox label that will wrap to multiple lines")
checkbox.iconAlignment = .top
Programmatic selection
let checkbox = Checkbox("Option A")
checkbox.isSelected = true
States and variants
Selection states
|
State |
Property |
Description |
|---|---|---|
|
Normal |
isSelected = false |
Default unselected state |
|
Selected |
isSelected = true |
Checked state |
|
Indeterminate |
indeterminate = true |
Partial selection state |
Visual states
|
State |
Property |
Description |
|---|---|---|
|
Enabled |
isEnabled = true |
Default interactive state |
|
Disabled |
isEnabled = false |
Non-interactive state with dimmed appearance |
|
Error |
hasError = true |
Error state with danger styling |
// Disabled state
checkbox.isEnabled = false
// Error state
checkbox.hasError = true
// Indeterminate state
checkbox.indeterminate = true
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.checkbox |
Default checkbox style. |
Events
|
Event |
Type |
Description |
|---|---|---|
|
selectionChanged |
((Bool) -> Void)? |
Called when the checkbox selection changes. |
Accessibility
The Checkbox has built-in accessibility support with configurable labels for different states.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
Descriptive label for screen readers |
String? |
|
accessibilityLabelConfigurator |
Configures accessibility label based on state |
(Bool, Checkbox) -> Void |
Best practices
- The checkbox automatically announces its selection state
- Error states are communicated to assistive technologies
- Custom accessibility labels can be configured per state
Localizable strings
Override these strings to customize accessibility text:
"DesignSystem.checkBox.accessibility.checkbox" = "%@, checkbox";
"DesignSystem.checkBox.accessibility.error" = "%@, showing error";
"DesignSystem.checkBox.accessibility.selected" = "%@, selected";
"DesignSystem.checkBox.accessibility.unselected" = "%@, unselected";
"DesignSystem.checkBox.accessibility.undetermined" = "%@, un-determined";
Dependencies
- External dependencies: None
- Internal dependencies: None
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.
Default state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.checkbox.default.background |
{theme.color.background.surface} |
|
Foreground |
theme.color.checkbox.default.foreground |
{theme.color.foreground.brand} |
|
Border |
theme.color.checkbox.default.border |
{theme.color.border.default} |
Selected state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.checkbox.selected.background |
{theme.color.foreground.brand} |
|
Foreground |
theme.color.checkbox.selected.foreground |
{theme.color.foreground.on-primary} |
|
Border |
theme.color.checkbox.selected.border |
{theme.color.foreground.brand} |
Error state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.checkbox.error.background |
{theme.color.background.surface} |
|
Foreground |
theme.color.checkbox.error.foreground |
{theme.color.foreground.danger} |
|
Border |
theme.color.checkbox.error.border |
{theme.color.foreground.danger} |
Disabled state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.checkbox.disabled.background |
{theme.color.background.surface} |
|
Foreground |
theme.color.checkbox.disabled.foreground |
{theme.color.foreground.disabled} |
|
Border |
theme.color.checkbox.disabled.border |
{theme.color.foreground.disabled} |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.primary.default |
Selected state color |
|
Colors |
Theme.colors.danger.default |
Error state color |
|
Colors |
Theme.colors.foreground.disabled |
Disabled state color |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.body, .semibold) |
Checkbox label font |
|
Styles |
DesignSystem.shared.styles.checkbox |
Default checkbox style |
See also