accessible-name
Mobile validation
Assistive technologies such as screen readers and voice control use an element's accessible name to convey its purpose and the result of activating it. Provide an accessible name for every interactive element, such as buttons, checkboxes, switches, and input fields. Non-text content that conveys information, such as images and icons, also needs an accessible name when it is essential to the content. Make accessible names specific, descriptive, and unique, so people can identify and activate the right element.
Pass Patterns
Android
The checkbox has no visible text, so android:contentDescription gives it a name.
<CheckBox
android:id="@+id/agreeCheckBox"
android:layout_width="..."
android:layout_height="..."
android:contentDescription="Agree" />The icon button takes its name from the icon's contentDescription.
IconButton(onClick = { ... }) {
Icon(
painter = painterResource(...),
contentDescription = "A valid content description",
)
}iOS
The switch has no visible text, so accessibilityLabel gives it a name.
let acceptSwitch = UISwitch()
acceptSwitch.isOn = false
acceptSwitch.accessibilityLabel = "Accept"The button shows only a decorative image, so accessibilityLabel gives it a name.
Button(action: pay) {
Image(decorative: "...")
}
.accessibilityLabel("A clear and descriptive accessibility label")Cross Platform
The Semantics widget gives the icon button a name with its label property.
child: Center(
child: Semantics(
label: 'Pay now',
button: true,
child: InkWell(
onTap: () => showPatternToast(context, 'Tapped'),
child: const Padding(
padding: EdgeInsets.all(12),
child: Icon(Icons.check, size: 48),
),
),
),
),The pressable icon has a name from accessibilityLabel.
<Pressable
accessibilityRole="button"
accessibilityLabel="Pay now"
onPress={...}
>
<Image source={...} />
</Pressable>Fail Patterns
Android
The checkbox has no text and no contentDescription, so it has no name.
<CheckBox
android:id="@+id/agreeCheckBox"
android:layout_width="..."
android:layout_height="..." />The icon's contentDescription is null, so the button has no name.
IconButton(onClick = { ... }) {
Icon(
painter = painterResource(...),
contentDescription = null,
)
}iOS
The switch has no visible text and no accessibilityLabel, so it has no name.
let acceptSwitch = UISwitch()
acceptSwitch.isOn = falseThe button shows only a decorative image and has no accessibilityLabel, so it has no name.
Button {
...
} label: {
Image(systemName: "...")
}
.accessibilityLabel("")Cross Platform
The Semantics widget marks the element as a button but gives it no label, and the icon has no semanticLabel.
child: Center(
child: Semantics(
button: true,
child: InkWell(
onTap: () => ...,
child: const Padding(
padding: EdgeInsets.all(12),
child: Icon(Icons.check, size: 48),
),
),
),
),The pressable contains only an image and has no accessibilityLabel, so it has no name.
<Pressable accessibilityRole="button" onPress={pay}>
<Image source={...} />
</Pressable>Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Turn on VoiceOver on iOS, or TalkBack on Android.
- Swipe right or left to move to the element.
- Listen to what the screen reader announces.
Expected results: The screen reader announces the element's accessible name, for example “Pay now, button”.
Actual results: The screen reader announces only the element's type, such as “button”, or “Unlabeled” on Android. On iOS, it may announce an image's file name instead of a meaningful name.
Using developer tools
- iOS: In Xcode, open Xcode > Open Developer Tool > Accessibility Inspector, select the simulator or device, and point at the element.
- Android: Go to the Running devices panel in Android Studio. Load the device screen and open the Layout Inspector. Find the attributes of the component and check that one of the following is true:
- The
textattribute is present and not empty and the field does not haveimportantForAccessibilityset tofalse. - The
contentDescriptionis present and not empty and the field does not haveimportantForAccessibilityset tofalse. - A parent container meets the above 2 conditions if the element has
importantForAccessibilityset totrue.
- The
Expected results: In Accessibility Inspector, the element's Label shows its name. Accessibility Scanner reports no item label issue for the element.
Actual results: There is no text or contentDescription set, and the element is focusable.
FAQ
How does this issue relate to 1.3.1 Info and Relationships?
WCAG 1.3.1 requires that information, structure, and relationships shown visually are also programmatically available or provided in text. The accessible name is how an interactive element exposes its purpose in code so assistive technology can present it to the user.
If a control lacks an accessible name, the purpose seen on screen is not available programmatically. This breaks the relationship between a control and its label, making it hard for people using assistive technology to find and activate the right element.
How this maps to 1.3.1:
- Buttons, links, and form fields need a programmatically determinable
accessible name - Icon-only controls require an
accessible namebecause their meaning is otherwise only visual - Images or graphics that convey information or act as controls need a text alternative used as their
accessible name - Specific and unique names help distinguish related controls and preserve relationships among them
Providing clear accessible name values satisfies 1.3.1 for these elements and ensures assistive technology can convey purpose and relationships accurately
How does this issue relate to 2.4.6 Headings and labels?
WCAG 2.4.6 requires headings and labels to describe their topic or purpose. An accessible name is the programmatic label for an interactive element. It tells assistive technology what the element is and what activating it will do.
When you give every button, link, and input a specific, descriptive, and unique accessible name, you meet the intent of 2.4.6. The same applies to essential non-text content that conveys information.
Missing, vague, or duplicate accessible names make purpose unclear. That creates an accessibility barrier because people cannot identify or activate the right element with confidence.
How does this issue relate to 4.1.2 Name, role, value?
SC 4.1.2 requires every user interface component to have a programmatically determinable name, role, and value or state. The accessible name is the name part. When an element has no accessible name, assistive technologies cannot convey its purpose, and voice control users cannot target it by name.
Why is this issue marked as Critical?
Without an accessible name, screen reader users cannot tell what an element is for or what activating it will do, and voice control users cannot activate it by name. People cannot find, understand, or use the control, which blocks key tasks, so it is rated critical.
Standards and Regulations
| Standard | Success Criterion | Reference |
|---|---|---|
| WCAG 2.2 | 1.3.1 Info and Relationships (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| WCAG 2.2 | 2.4.6 Headings and Labels (AA) | Headings and labels describe topic or purpose. |
| WCAG 2.2 | 4.1.2 Name, Role, Value (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | 11.1.3.1 Info and Relationships | Same as the WCAG text. |
| EN 301 549 | 11.2.4.6 Headings and Labels | Same as the WCAG text. |
| EN 301 549 | 11.4.1.2 Name, Role, Value | Same as the WCAG text. |
| Section 508 | 1194.21(d) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |