How it works
AccessibilityLabeledPairRole describes the part a view plays in a label-and-content pair so assistive technologies can read the two together as a single, meaningful unit. When information is split across separate views — a name on one side and its value on the other — VoiceOver would otherwise announce each in isolation, losing the relationship between them. Use this role to mark which view is the descriptive label and which is the value it labels, joining them into one accessibility element. Reach for it whenever a logical pairing is expressed through layout rather than through a single combined view.
Pair two views with accessibilityLabeledPair(role:id:in:)
The role is supplied to the
accessibilityLabeledPair(role:id:in:)modifier, which links two otherwise-independent views into one labeled pair. In the example the modifier is applied to both theText("Battery")view and theText("87%")view so SwiftUI treats them as the two halves of a single accessibility element.Identify the descriptive half with .label
The
.labelcase marks the view that names or describes the value — the part assistive technologies read first to establish context. Here it is attached toText("Battery"), declaring that this view is the label for the pair rather than a standalone piece of content.Identify the value with .content
The
.contentcase marks the view that holds the value being described, so it is announced as belonging to its label. In the example it is applied toText("87%"), telling SwiftUI that the percentage is the content paired with theBatterylabel.Join the roles with a shared id and namespace
A pair is bound together by giving both views the same
idwithin one@Namespace, which is how AccessibilityLabeledPairRole knows the.labeland.contentbelong to each other. Both modifiers use the id"battery"inside thepairnamespace declared with@Namespace private var pair, so the twoTextviews resolve to one element.
Text("Battery") role .content and Text("87%") role .label — and listen as VoiceOver reverses which view it treats as the description and which as the value.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 AccessibilityLabeledPairRoleDemo: View {
@Namespace private var pair
var body: some View {
HStack {
Text("Battery")
.accessibilityLabeledPair(role: .label, id: "battery", in: pair)
Spacer()
Text("87%")
.bold()
.accessibilityLabeledPair(role: .content, id: "battery", in: pair)
}
.padding()
}
}