Structure
OUDSCheckboxItem
Checkbox is a UI element that allows to select multiple options from a set of mutually non exclusive choices. Checkbox item covers a wider range of contexts by allowing to toggle the visibility of additional text labels and icon assets.
- iOS 15.0+
- macOS 13.0+
- tvOS 16.0+
- visionOS 1.0+
- watchOS 11.0+
@MainActor struct OUDSCheckboxItem
Mentioned In
Layouts
The component can be rendered as two different layouts:
default: the component has a leading indicator, a label and optional helper texts, and an optional trailing decorative icon
reversed: like the default layout but with a trailing checkbox indicator and a leading optional image
Indicator states
The checkbox indicator has three available states:
selected: the checkbox is filled with a tick, the user has made the action to select the checkbox
unselected: the checkbox is empty, does not contain a tick, the user has made the action to unselect or did not select yet the checkbox
If you are looking for a checkbox component with three states, use instead OUDSCheckboxItemIndeterminate.
Particular cases
An OUDSCheckboxItem can be related to an error situation, for example troubles for a formular. A dedicated look and feel is implemented for that if the isError flag is risen. In that case if the component displayed an icon, this icon will be replaced automatically by an error icon.
In addition, the OUDSCheckboxItem can be in read only mode, i.e. the user cannot interact with the component yet but this component must not be considered as disabled.
The component does not follow the right-to-left (RTL) / left-to-right (LTR) mode returned by the system as it could have some meaning to have for example the indicator in trailing position for LTR mode and vice versa. However, if the component has an icon in leading position (RTL mode) or in trailing position (LTR), the content of the icon is never changed. It could lead to a loss of meaning or semantics in the icon. Thus a specific flag can be used to flip the icon content whatever the layout direction is. It prevents the user do implement its own rules to flip or not image.
Rich text
Rich text can only be used for error messages.
Strong text can be used sparingly to highlight key information within the content. No other text styles should be used. Underlined text must not be applied manually (e.g. in error message), as it is commonly associated with hyperlinks and may mislead users.
Accessibility considerations
Always check the results of rich text mode with high contrast, light and dark modes, and Voice Over vocalization.
Voice Over will use several elements to describe the component: if component disabled / read only, if error context, the label and helper texts and a custom checkbox trait. No accessibility identifier is defined in OUDS side as this value remains in the users hands.
Forbidden by design
The design system does not allow to have both an error situation and a read only component. The design system does not allow to have both an error situation and a disabled component. The design system does not allow to have both a read only and a disabled component.
Code samples
// Supposing we have an unselected checkbox
@Published var isOn: Bool = false
// A leading checkbox with a label.
// The default layout will be used here.
OUDSCheckboxItem("Hello world", isOn: $isOn)
// Localizable from bundle can also be used
OUDSCheckboxItem(LocalizedStringKey("agree_terms"), bundle: Bundle.module, isOn: $isOn)
// A leading checkbox with a label, but in read only mode (user cannot interact yet, but not disabled).
// The default layout will be used here.
OUDSCheckboxItem("Hello world", isOn: $isOn, isReadOnly: true)
// A leading checkbox with a label and a description as helper text.
// The default layout will be used here.
OUDSCheckboxItem("Bazinga!", isOn: $isOn, description: "Doll-Dagga Buzz-Buzz Ziggety-Zag")
// A trailing checkbox with a label, a description and an icon.
// The reversed layout will be used here.
OUDSCheckboxItem("We live in a fabled world",
isOn: $isOn,
description: "Of dreaming boys and wide-eyed girls",
isReversed: true,
icon: Image(decorative: "ic_heart"))
// If on error, add an error message can help user to understand error context
OUDSCheckboxItem("We live in a fabled world",
isOn: $isOn,
isError: true,
errorText: "Something wrong",
hasDivider: true)
// A leading checkbox with a label, but disabled.
// The default layout will be used here.
OUDSCheckboxItem("Hello world", isOn: $isOn)
.disabled(true)
// Never disable a read only or an error-related checkbox as it will crash
// This is forbidden by design!
OUDSCheckboxItem("Hello world", isOn: $isOn, isError: true).disabled(true) // fatal error
OUDSCheckboxItem("Hello world", isOn: $isOn, isReadOnly: true).disabled(true) // fatal error
If you need to flip your icon depending to the layout direction or not (e.g. if RTL mode lose semantics / meanings):
@Environment(\.layoutDirection) var layoutDirection
OUDSCheckboxItem("Cocorico !",
isOn: $selection,
icon: Image(systemName: "figure.handball"),
flipIcon: layoutDirection == .rightToLeft,
isInversed: layoutDirection == .rightToLeft)
Suggestions
According to the documentation, the checkbox by default must be used in unselected state.
Design documentation
unified-design-system.orange.com
Themes rendering
Orange
Orange Compact
Sosh
Wireframe
Version
2.4.0 (Figma component design version)
Since
0.12.0
Topics
Initializers
init(String, isOn: Binding<Bool>, description: String?, icon: Image?, flipIcon: Bool, isReversed: Bool, isError: Bool, errorText: AttributedString, isReadOnly: Bool, hasDivider: Bool, constrainedMaxWidth: Bool, action: (() -> Void)?)Creates a checkbox with label and optional helper text, icon, divider.
init(String, isOn: Binding<Bool>, description: String?, icon: Image?, flipIcon: Bool, isReversed: Bool, isError: Bool, errorText: String?, isReadOnly: Bool, hasDivider: Bool, constrainedMaxWidth: Bool, action: (() -> Void)?)Creates a checkbox with label and optional helper text, icon, divider.
init(LocalizedStringKey, tableName: String?, bundle: Bundle, isOn: Binding<Bool>, description: String?, icon: Image?, flipIcon: Bool, isReversed: Bool, isError: Bool, errorText: String?, isReadOnly: Bool, hasDivider: Bool, constrainedMaxWidth: Bool, action: (() -> Void)?)Creates a checkbox with a localized label, looking up the key in the given bundle.
init(LocalizedStringKey, tableName: String?, bundle: Bundle, isOn: Binding<Bool>, description: String?, icon: Image?, flipIcon: Bool, isReversed: Bool, isError: Bool, errorText: AttributedString, isReadOnly: Bool, hasDivider: Bool, constrainedMaxWidth: Bool, action: (() -> Void)?)Creates a checkbox with a localized label, looking up the key in the given bundle.
Instance Properties