How it works
AccessibilityChildBehavior describes what an assistive technology like VoiceOver should do with the accessibility elements that a view contains. When you merge a subtree into a single accessibility element with accessibilityElement(children:), you pass a value of this type to say whether those child elements are folded into the parent, kept as the parent's descendants, or ignored entirely. Reach for it whenever a group of views reads as one logical control or summary, and you want to shape how its pieces are presented rather than letting SwiftUI infer the structure.
Pass the behavior to accessibilityElement(children:)
AccessibilityChildBehavioris the argument type of theaccessibilityElement(children:)modifier. Applying that modifier to a container promotes it into one accessibility element, and the behavior you supply decides what happens to the labels and traits of the views inside. In the demo, both cardVStacks call this modifier so each card becomes a single navigable element instead of several.Collapse children into one label with .combine
The
.combinevalue merges the accessibility information of the descendant elements into the new parent, concatenating their labels and combining their traits. The first card wrapsText("Total")andText("$42.00")with.accessibilityElement(children: .combine), so VoiceOver announces a single element reading "Total, $42.00" rather than stopping on each line separately.Keep children as descendants with .contain
The
.containvalue makes the view an accessibility element whose children remain reachable as contained elements, so users can still navigate into them. The second card applies.accessibilityElement(children: .contain)aroundText("Items")andText("3 in cart"), exposing the container as a group that holds its labels instead of flattening them into one announcement.Hide children with .ignore (the default)
Passing
.ignore— which is the default when you callaccessibilityElement()with no argument — turns the view into a single element and drops the accessibility data of everything inside, expecting you to supply your own label and value. Choose it when the child text is decorative or you intend to describe the element yourself with modifiers likeaccessibilityLabel(_:).Treat it as a plain value type
AccessibilityChildBehavioris astructwith no public initializer; you select behavior through its static members.combine,.contain, and.ignorerather than constructing one. Because it is just a value, you can compute or branch on which behavior to pass — for example switching between.combineand.containdepending on whether a card should read as a summary or as a navigable group like the two cards here.
.accessibilityElement(children: .combine) to .accessibilityElement(children: .contain) and run VoiceOver: the "Total" and "$42.00" lines stop merging into one phrase and become separately reachable inside the card.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct AccessibilityChildBehaviorDemo: View {
var body: some View {
VStack(alignment: .leading, spacing: 16) {
VStack(alignment: .leading) {
Text("Total")
.font(.caption)
.foregroundStyle(.secondary)
Text("$42.00")
.font(.title.bold())
}
.padding()
.background(.blue.opacity(0.1), in: RoundedRectangle(cornerRadius: 12))
.accessibilityElement(children: .combine)
VStack(alignment: .leading) {
Text("Items")
.font(.caption)
.foregroundStyle(.secondary)
Text("3 in cart")
.font(.title.bold())
}
.padding()
.background(.green.opacity(0.1), in: RoundedRectangle(cornerRadius: 12))
.accessibilityElement(children: .contain)
}
.padding()
}
}