Digital Accessibility Knowledge Base

    alternative-text

    Images, infographics, and media elements must have a textual alternative that can be read and announced programmatically.

    Who might be affected
    Low Vision
    Screen Reader

    Description

    Images and graphic elements in the interface should have a textual alternative that can be read by assistive technologies such as a screen reader. The text alternative should describe the image's content so that its meaning and context on the page are clear. However, effective alternative text phrasing depends on the context and specific purpose of the graphic element. To learn more about how to phrase a text alternative according to the image's context and meaning, see the “Images Tutorial” by the WAI. However, note that there is an exception. When the image or graphic element is intended for decorative purposes only, that is, it is designed only to enrich the appearance and has no meaning or effect in understanding or operating the content, an alternative text is not required, but in such cases, the element must be hidden from assistive technologies.

    Quick Fixes

    Add text alternatives to all images, infographics and media elements, or hide them from assistive technologies.

    Android

    XML (Fail techniques)

    1<ImageView
    2    android:id="@+id/imageView"
    3    android:layout_width="wrap_content"
    4    android:layout_height="wrap_content"
    5    android:src="@drawable/my_image"/>

    XML (Pass techniques)

    1<ImageView
    2    android:id="@+id/imageView"
    3    android:layout_width="wrap_content"
    4    android:layout_height="wrap_content"
    5    android:src="@drawable/my_image"
    6    android:contentDescription="@string/image_description"/>
    1<ImageView
    2    android:id="@+id/imageView"
    3    android:layout_width="wrap_content"
    4    android:layout_height="wrap_content"
    5    android:src="@drawable/my_image"
    6    android:importantForAccessibility="no"/>

    * Use the technique above (the second one) only when the image is meant purely for decorative purposes.

    Java (Fail techniques)

    1ImageView imageView = findViewById(R.id.imageView);
    2imageView.setImageResource(R.drawable.my_image);

    Java (Pass techniques)

    1ImageView imageView = findViewById(R.id.imageView);
    2imageView.setImageResource(R.drawable.my_image);
    3imageView.setContentDescription(getString(R.string.image_description));
    1ImageView imageView = findViewById(R.id.imageView);
    2imageView.setImageResource(R.drawable.my_image);
    3imageView.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_NO);

    * Use the technique above (the second one) only when the image is meant purely for decorative purposes.

    Kotlin (Fail techniques)

    1val imageView: ImageView = findViewById(R.id.imageView)
    2imageView.setImageResource(R.drawable.my_image)

    Kotlin (Pass techniques)

    1val imageView: ImageView = findViewById(R.id.imageView)
    2imageView.setImageResource(R.drawable.my_image)
    3imageView.contentDescription = getString(R.string.image_description)
    1val imageView: ImageView = findViewById(R.id.imageView)
    2imageView.setImageResource(R.drawable.my_image)
    3imageView.importantForAccessibility =View.IMPORTANT_FOR_ACCESSIBILITY_NO

    * Use the technique above (the second one) only when the image is meant purely for decorative purposes.

    iOS

    UIKit (Fail techniques)

    1let dataImage = UIImage(data: data)
    2let imageView = UIImageView(image: dataImage)

    UIKit (Pass techniques)

    1let dataImage = UIImage(data: data)
    2let imageView = UIImageView(image: dataImage)
    3imageView.isAccessibilityElement = true
    4imageView.accessibilityLabel = "Describe the image here"

    UIKit, Objective C (Fail techniques)

    1UIImage *dataImage = [UIImage imageWithData:data];
    2if (dataImage) {
    3    UIImageView *imageView = [[UIImageView alloc] initWithImage:dataImage];
    4}

    UIKit, Objective C (Pass techniques)

    1UIImage *dataImage = [UIImage imageWithData:data];
    2if (dataImage) {
    3    UIImageView *imageView = [[UIImageView alloc] initWithImage:dataImage];
    4    imageView.accessibilityLabel = @"Describe the image here";
    5}

    SwiftUI (Fail techniques)

    1struct ContentView: View {
    2    let imageData: Data
    3

    4    var body: some View {
    5        if let uiImage = UIImage(data: imageData) {
    6            Image(uiImage: uiImage)
    7        }
    8    }
    9}

    SwiftUI (Pass techniques)

    1struct ContentView: View {
    2    let imageData: Data
    3

    4    var body: some View {
    5        if let uiImage = UIImage(data: imageData) {
    6            Image(uiImage: uiImage)
    7			.accessibilityLabel("Describe the image here")
    8        }
    9    }
    10}

    How Users Are Affected

    Rich content containing images and media is the forefather of mobile apps. Still, due to the visual nature of this type of content, blind and visually impaired users can only perceive it if it has text alternatives.

    WCAG Success criteria

    This issue might cause elements to fail one or more of the following Success criteria:
    1.1.1 Non-text Content (A)