Checkbox (Group)
Several checkboxes that together answer one question, any number of them checked. Nothing on Android ties a label to a set of controls, and selectableGroup does nothing for checkboxes, so the set's name, its position information, and its one group-level error are all the caller's.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when several checkboxes together answer one question and each option's label is not meaningful without it (e.g., "How should we contact you?" with "Email", "Text message", "Phone call").
- Use when the user may check none, one, or several of the options, and the set may need one requirement checked as a whole (e.g., "Select at least one").
Try a different component when
- Do not use when a single checkbox stands on its own (use
checkbox.basic). - Do not use when exactly one option may be chosen (use
radio.basic). - Do not use when a parent checkbox checks or clears the whole set (use
checkbox.tristate). - Do not use when two to five short options sit side by side as one connected control (use
segmented-button.basic). - Do not use when the options filter a set of results (use
chip.filter).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- Build each option as a checkbox row, as
checkbox.basicdescribes: the row carriesModifier.toggleable(role = Role.Checkbox), theCheckboxinside itonCheckedChange = null, and the row is at least 48dp tall. - Give the set a visible label that states its question, marked with
heading(), and name the container holding the options withModifier.semantics { contentDescription = "..." }matching it. Nothing associates a visible label with a set of controls on Android, so a user who reaches the options by any route other than the label does not otherwise hear the question (global.collection-semantics,global.headings). - Declare the set on the container with
collectionInfo = CollectionInfo(rowCount = count, columnCount = 1), and each option's place withcollectionItemInfo = CollectionItemInfo(rowIndex = index, rowSpan = 1, columnIndex = 0, columnSpan = 1)on its row.selectableGroup()derives position only from selectable children, so it adds nothing to checkbox rows (global.collection-semantics). - Put a group-level hint (e.g., "Select at least one") in visible text after the label and before the first option, so it is read on the way into the set. Compose has nothing that attaches a hint to each option.
- When the set's requirement is not met, show one error for the whole set, in visible text after the label, and announce it once by making that text a polite live region (
global.announcements). Check the requirement when the form is submitted, not as each option changes, and leave focus where it is. - Meets the focus states baseline in
global_rules.md(global.focus-states).
Donts
Avoid these accessibility and UX barriers.
- Do not add
selectableGroup()to the container to report the set. It compiles, adds nothing for checkboxes, and looks like the fix. - Do not set
error()on every option for a requirement that belongs to the set. The user hears the same error at each stop. - Do not give the options radio semantics or
Modifier.selectable. Checkboxes allow several choices, andRole.RadioButtontells the user only one counts. - Do not make the container clickable or set
mergeDescendantson it. The options collapse into one stop and can no longer be checked one at a time (global.merge-semantics). - Do not combine unrelated questions in one set; give each question its own container and name.
Customizable
Alternatives and options that give the AI agent some room to move.
- The options may be laid out in a column, a grid, or a wrapping flow, provided the collection properties report their real rows and columns.
- The hint may be left out when the set has no requirement.
- The visible label may be a heading or plain text styled as a label, provided the container's
contentDescriptionmatches it.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun CheckboxGroupExamples(showError: Boolean) {
val methods = listOf("Email", "Text message", "Phone call")
val checked = remember { mutableStateListOf(false, false, false) }
Column {
Text(
"How should we contact you?",
modifier = Modifier.semantics { heading() }
)
Text("Select at least one.")
if (showError) {
Text(
"Choose at least one way to contact you.",
modifier = Modifier.semantics { liveRegion = LiveRegionMode.Polite }
)
}
Column(
modifier = Modifier.semantics {
contentDescription = "How should we contact you?"
collectionInfo = CollectionInfo(rowCount = methods.size, columnCount = 1)
}
) {
methods.forEachIndexed { index, method ->
Row(
modifier = Modifier
.toggleable(
value = checked[index],
onValueChange = { checked[index] = it },
role = Role.Checkbox
)
.heightIn(min = 48.dp)
.fillMaxWidth()
.semantics {
collectionItemInfo = CollectionItemInfo(
rowIndex = index,
rowSpan = 1,
columnIndex = 0,
columnSpan = 1
)
},
verticalAlignment = Alignment.CenterVertically
) {
Checkbox(checked = checked[index], onCheckedChange = null)
Text(method)
}
}
}
}
}