JsonUI
← GuidesScreen readersTwo attributes tell a screen reader what a layout cannot say by itself, on all three platforms: `accessibilityLabel` names a control by something other than what it shows, and `accessibilityLiveRegion` reads a text out when it changes. Every code block on this page is what the shipped converters write for the layout above it. A third, `accessibilitySelected`, says which of a set of buttons is the chosen one (section 4).~4 min read
1. Two attributes`accessibilityLabel` (also spelled `contentDescription`) goes on a control: Button, CheckBox, Switch, Radio, Segment, Slider, SelectBox, TextField, and a View with a tap of its own. `accessibilityLiveRegion` goes on a Label or a View and takes `polite`, `assertive` or `off`. Both are optional, and this site writes neither.Both in one layout:
layout
{
"type": "View", "orientation": "vertical",
"child": [
{ "type": "Button", "id": "open_button", "text": "Open",
"onClick": "@{onOpen}",
"accessibilityLabel": "Open the second image" },
{ "type": "Label", "id": "save_status", "text": "@{saveStatus}",
"accessibilityLiveRegion": "polite" }
]
}
• An Image is not on the list because it already has a name: `alt`, which takes `accessibilityLabel` and `contentDescription` as other spellings. IconLabel's `contentDescription` is its icon's name, a separate attribute.
2. accessibilityLabel: the name a control is read byA screen reader reads a control by what it shows. Where that is not enough, as with a row's "Open" that should be read "Open the second image", the label replaces it. The value is a strings.json key or text, localized like `text`, or a binding. Each platform writes it where its screen reader looks: web `aria-label` on the element that takes focus, iOS `.accessibilityLabel(Text(…))` last on the chain, Android `contentDescription` in the semantics of the modifier.One Button, through the three converters:
generated (excerpts)
// web (rjui)
<button id="open_button" className="…" onClick={() => data.onOpen?.()}
aria-label="Open the second image">Open</button>
 
// iOS (sjui, SwiftUI)
StateAwareButtonView(
text: "Open",
action: { data.onOpen?() },
isEnabled: true
)
.accessibilityIdentifier("open_button")
.accessibilityLabel(Text("Open the second image"))
 
// Android (kjui, Compose)
Button(onClick = { data.onOpen?.invoke() },
modifier = Modifier
.testTag("open_button")
.semantics { testTagsAsResourceId = true }
.then(("Open the second image").let { label -> Modifier.semantics { contentDescription = label } }),
…) { Text("Open") }
• A binding is written as one: `"contentDescription": "@{openLabel}"` became `aria-label={`${data.openLabel ?? ""}`}` on web.• On a View the name lands only when the View is one button to a screen reader, that is when it has an `onClick` of its own. A View that taps nothing is not one element, so the name would land on its children instead, and it is not written: on web the View with `onClick` got `aria-label="Open item"` and the same View without it got nothing.
3. accessibilityLiveRegion: text read out when it changesA saved or failed line, or a progress count, changes where focus is not, and a screen reader says nothing about it unless told to. `polite` reads the new text when the screen reader has finished what it is saying; `assertive` interrupts it, for an error; `off`, or leaving the attribute out, reads nothing. Web and Android have live regions and write one. iOS has none, so a Label whose text is bound posts an announcement of the new text each time it changes.Two Labels, through the three converters:
generated (excerpts)
// layout
{ "type": "Label", "id": "save_status", "text": "@{saveStatus}", "accessibilityLiveRegion": "polite" }
{ "type": "Label", "id": "save_error", "text": "@{saveError}", "accessibilityLiveRegion": "assertive" }
 
// web (rjui)
<span id="save_status" className="…" role="status" aria-live="polite">{`${data.saveStatus ?? ""}`}</span>
<span id="save_error" className="…" role="alert" aria-live="assertive">{`${data.saveError ?? ""}`}</span>
 
// Android (kjui, Compose) — on each Text's modifier
.semantics { liveRegion = LiveRegionMode.Polite }
.semantics { liveRegion = LiveRegionMode.Assertive }
 
// iOS (sjui, SwiftUI) — save_status; save_error is the same with .high
.onChange(of: (data.saveStatus ?? "")) { _, newValue in
var announcement = AttributedString(newValue)
announcement.accessibilitySpeechAnnouncementPriority = .default
AccessibilityNotification.Announcement(announcement).post()
}
• `off` writes nothing on web: the Label came out exactly as one without the attribute.• On iOS the announcement follows a bound text. A static text never changes, so it announces nothing; put the attribute on a Label whose text is `@{…}`.• On a View the attribute is written on web (`role` and `aria-live` on the View) and Android (`liveRegion`), and on iOS it does nothing: a View holds no one text to announce. The build does not warn about it, because one layout is written for all three platforms. To be read out on iOS too, put it on the Label whose text changes rather than on the View around it.
4. accessibilitySelected, and controls that say their own state`accessibilitySelected` takes true or a binding and tells a screen reader that a button is the selected one, such as one of two buttons used as a choice: the selected trait on iOS, semantics selected on Android, aria-pressed on the web. false tells nothing on all three, as VoiceOver says nothing of a control that is not selected. It takes effect on a Button, and on a View or IconLabel whose onClick makes it one button.What the web converter writes:
generated (web, excerpts)
Button, accessibilitySelected: true aria-pressed="true"
Button, accessibilitySelected: @{isA} aria-pressed={(data.isA) ? true : undefined}
Button, accessibilitySelected: false (nothing)
View with onClick, @{isA} aria-pressed={(data.isA) ? true : undefined}
IconLabel with onClick, @{isA} aria-pressed={(data.isA) ? true : undefined}
View without onClick, true (nothing; the validator warns)
 
Segment, selectedIndex @{i} aria-pressed={data.i === 0}, aria-pressed={data.i === 1}
Switch role="switch"
TabView role="tablist", role="tab" aria-selected={… === 0}
• Anywhere else the validator warns and nothing is told: a View without an onClick, or a tappable View that holds a control of its own ("accessibilitySelected tells a screen reader nothing here"). A Button, or a View or IconLabel with an onClick and no control inside, gets no warning.• Controls that have a state say it themselves, without this attribute. On the web a Segment's buttons carry aria-pressed for the selected one, a Switch is role="switch", and a TabView is a tablist of tabs with aria-selected. jsonui-cli says iOS's Radio and CheckBox read their selected state too.
5. What this page measured, and what it did notThe code blocks are the converters' output, measured on the layouts shown. Nothing here ran a screen reader: whether VoiceOver, TalkBack or a browser's reader then says the name, or reads the change, is the platform's behaviour and is not measured on this page. This site draws none of these controls with either attribute, so its own pages are no example of them. Section 4 was measured the same way, with the Button, View, IconLabel, Segment, Switch and TabView converters and the attribute validator; iOS and Android output for it was not read here.
Keep reading
Writing layoutsWhere these attributes sit among the rest of a layout./guides/writing-layouts
LocalizationHow a strings.json key in a label is resolved per language./guides/localization
TestingFinding controls in UI tests, which reads ids rather than these names./guides/testing