Alternative Text (Mobile)

Images, infographics, and other media must have a text alternative that assistive technologies can announce programmatically.

Provide a text alternative for each image or graphic, so assistive technologies can convey its purpose. Write the text alternative based on the image's role in context: describe its meaning and function, not every visual detail. When an image is exposed to assistive technologies but has no text alternative, screen readers announce only “image”, “unlabeled”, or on iOS sometimes the image's file name, and users miss the information the image conveys.

Note: If an image is purely decorative and adds no information or functionality, don't give it a text alternative. Hide it from assistive technologies instead, so screen readers skip it.

Pass Patterns

Android

The image has a text alternative in android:contentDescription.

XML

<ImageView
    android:id="@+id/logoImage"
    android:layout_width="..."
    android:layout_height="..."
    android:src="@drawable/..."
    android:contentDescription="Company logo" />

A decorative image is hidden from assistive technologies with android:importantForAccessibility="no".

XML

<ImageView
    android:id="@+id/dividerImage"
    android:layout_width="..."
    android:layout_height="..."
    android:src="@drawable/..."
    android:importantForAccessibility="no" />

The image has a text alternative in contentDescription.

Kotlin

Image(
    painter = painterResource(R.drawable...),
    contentDescription = "Company logo",
)

A decorative image uses contentDescription = null, so assistive technologies skip it.

Kotlin

Image(
    painter = painterResource(R.drawable...),
    contentDescription = null,
)

iOS

The image view is an accessibility element with a text alternative in accessibilityLabel.

Swift

let logoImageView = UIImageView(image: UIImage(named: "..."))
logoImageView.isAccessibilityElement = true
logoImageView.accessibilityLabel = "Company logo"

The image has a text alternative in accessibilityLabel.

Swift

if let uiImage = UIImage(data: imageData) {
    Image(uiImage: uiImage)
        .accessibilityLabel("Company logo")
}

A decorative image uses Image(decorative:), so assistive technologies skip it.

Swift

Image(decorative: "divider")

Cross Platform

The image has a text alternative in semanticLabel.

Dart

Image.asset(
  'assets/...',
  semanticLabel: 'Company Logo',
  width: ...,
  height: ...,
)

The image is accessible and has a text alternative in accessibilityLabel.

TSX

<Image
  source={require('...')}
  style={{ width: ..., height: ... }}
  accessible
  accessibilityLabel="Company logo"
/>

TSX

<Image
  source={require('../../../assets/a11y.png')}
  style={styles.image}
  accessible
  accessibilityLabel="android logo"
  importantForAccessibility="yes"
/>

Fail Patterns

Android

The image is exposed to assistive technologies, but it has no contentDescription.

XML

<ImageView
    android:id="@+id/logoImage"
    android:layout_width="..."
    android:layout_height="..."
    android:focusable="true"
    android:src="@drawable/..."
    android:importantForAccessibility="yes"
    android:screenReaderFocusable="true" />

The image can receive focus, but its contentDescription is empty.

Kotlin

Image(
    painter = painterResource(R.drawable.a11y),
    contentDescription = "",
    modifier = Modifier
        ...
        .semantics { contentDescription = "" }
        .focusable(),
)

iOS

The image view is an accessibility element, but it has no accessibilityLabel.

Swift

let logoImageView = UIImageView(image: UIImage(named: "..."))
logoImageView.isAccessibilityElement = true

The image is created from data, so it has no name, and it has no accessibilityLabel.

Swift

Image(systemName: "...")
    .accessibilityElement()
    .accessibilityAddTraits(.isImage)

Cross Platform

The image has no semanticLabel.

Dart

child: Semantics(
  container: true,
  child: Focus(
    child: Image.asset(
      'assets/logo.png',
       width: 100,
       height: 100,
     ),
   ),
),

The image is accessible, but it has no accessibilityLabel.

TSX

<Image
  source={require('...')}
  style={{ width: ..., height: ... }}
  accessible
/>

TSX

<Pressable focusable>
  <Image
    source={require('../../../assets/a11y.png')}
    style={styles.image}
    accessible
    importantForAccessibility="yes"
  />
</Pressable>

Try It Yourself

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 image.
Listen to what the screen reader announces.

Expected results: The screen reader announces a text alternative that conveys the image's purpose, or skips the image if it is decorative.

Actual results: The screen reader announces only “image” or “unlabeled”, or on iOS the image's file name.

Using developer tools

iOS: In Xcode, open Xcode > Open Developer Tool > Accessibility Inspector, select the simulator or device, and point at the image.
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:
1. The text attribute is present and not empty and the field does not have importantForAccessibility set to false.
2. The contentDescription is present and not empty and the field does not have importantForAccessibility set to false.
3. A parent container meets the above 2 conditions if the element has importantForAccessibility set to true.

Expected results: In Accessibility Inspector, the image's Label shows its text alternative. Accessibility Scanner reports no item label issue for the image.

Actual results: The Label is empty.

FAQ

How does this issue relate to 1.1.1 Non-text Content?

SC 1.1.1 requires non-text content to have a text alternative that serves the equivalent purpose. When an image is exposed to assistive technologies without a text alternative, screen reader users cannot perceive the information it conveys, so the criterion is not met. Decorative images are an exception, but they must be hidden from assistive technologies.

Why is this issue marked as Critical?

When an image conveys information or acts as a control, a missing text alternative makes its purpose invisible to screen reader users. They may miss key content or be unable to complete a task that depends on the image, so it is rated critical.

Standards and Regulations

Standard	Success Criterion	Reference
WCAG 2.2	1.1.1 Non-text Content (A)	All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for controls/input, time-based media, tests, sensory experiences, CAPTCHA, and decoration/formatting/invisible content.
EN 301 549	11.1.1.1 Non-text Content	Same as the WCAG text.

alternative-text

Pass Patterns

Android

iOS

Cross Platform

Fail Patterns

Android

iOS

Cross Platform

Try It Yourself

Using developer tools

FAQ

Standards and Regulations

Personas impacted by this issue

Learn More

alternative-text

Pass Patterns

Android

iOS

Cross Platform

Fail Patterns

Android

iOS

Cross Platform

Try It Yourself

Using a screen reader

Using developer tools

FAQ

Standards and Regulations

Personas impacted by this issue

Learn More

Related Issues