OUDSCheckboxItemIndeterminate

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 OUDSCheckboxItemIndeterminate

Mentioned In

Controls

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
inverse: 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
indeterminate: mike a prefilled or preticked checkbox, the user did not do anything on it yet

If you need a checkbox with only two states to manage use instead OUDSCheckboxItem.

Particular cases

An OUDSCheckboxItemIndeterminate 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 OUDSCheckboxItemIndeterminate 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.

Accessibility considerations

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.

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 indeterminate state checkbox
    @Published var selection: OUDSCheckboxIndicatorState = .indeterminate

    // A leading checkbox with a label.
    // The default layout will be used here.
    OUDSCheckboxItemIndeterminate("Hello world", selection: $selection)

    // 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.
    OUDSCheckboxItemIndeterminate("Hello world", selection: $selection, isReadOnly: true)

    // A leading checkbox with a label and a description as helper text.
    // The default layout will be used here.
    OUDSCheckboxItemIndeterminate("Bazinga!", selection: $selection, description: "Doll-Dagga Buzz-Buzz Ziggety-Zag")

    // A trailing checkbox with a label, an helper text and an icon.
    // The reversed layout will be used here.
    OUDSCheckboxItemIndeterminate("We live in a fabled world",
                                  selection: $selection,
                                  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
    OUDSCheckboxItemIndeterminate("We live in a fabled world",
                                  selection: $selection,
                                  isError: true,
                                  errorText: "Something wrong",
                                  hasDivider: true)

    // A leading checkbox with a label, but disabled.
    // The default layout will be used here.
    OUDSCheckboxItemIndeterminate("Hello world", selection: $selection)
        .disabled(true)

    // A leading checkbox with a label and and icon but with the icon flipped vertically
    OUDSCheckboxItemIndeterminate("Cocorico !",
                                  selection: $selection,
                                  icon: Image(systemName: "figure.handball"),
                                  flipIcon: true)

    // Never disable a read only or an error-related checkbox as it will crash
    // This is forbidden by design!
    OUDSCheckboxItemIndeterminate("Hello world", selection: $selection, isError: true).disabled(true) // fatal error
    OUDSCheckboxItemIndeterminate("Hello world", selection: $selection, isReadOnly: true).disabled(true) // fatal error

If you want to manage the RTL mode quite easily and switch your layouts (flip image, indicator in RTL leading i.e. in the right):

    @Environment(\.layoutDirection) var layoutDirection

    OUDSCheckboxItemIndeterminate("Cocorico !",
                                  selection: $selection,
                                  icon: Image(systemName: "figure.handball"),
                                  flipIcon: layoutDirection == .rightToLeft,
                                  isReversed: layoutDirection == .rightToLeft)