accessibility-guidelines

This document is in beta. Help us by reporting issues via Github or email

Back to the overview page

Text alternative for images

On this page:

• Summary
• Requirements
• Guidance for Design
• Guidance for iOS
• Guidance for Android
• Guidance for Web
• More info

---

Summary

Provide an alternative text description for images. Make sure the description conveys the same message or functionality.

All non-text content (like images, charts, icons and infographics) must have an appropriate text equivalent.

---

Requirements

• Images (like logos and icons) that communicate information have short text alternatives that serve the same purpose as the image:

  • When the image conveys information (like an image that is part of a news article), the text alternative should convey the same information as the image.
  • When the purpose of the image is to convey a functionality (like a magnifying glass icon), the text alternative should describe the action that will be performed (like “search”).
    • Each should have a unique alternative to distinguish them from each other. For example, rather than multiple ‘share’ buttons with the same alternative “Share”, the alternative should be “Share …” and include the name of the related item.

• Endeavour to be succinct, and avoid redundant phrasing such as “Picture of …”, “… logo”, or “Select this to …”. Verbose alternatives make content harder to listen to and understand for screen reader users.

• The element type or trait, such as image or button, should not be included in the alternative as it is programmatically determined and added by the screen reader. For example:

  • A ‘play’ button coded as a button with the alternative “Play button” would be spoken as “Play button. Button.”.
  • An image coded as an image with an alternative beginning “Image of …” would be spoken as “Image. Image of …”.

Complex images

• Images (like infographics, charts and diagrams) that communicate complex information also have longer text descriptions within the same page.

Purely decorative and redundant images

• Images that are purely decorative (meaning that do not convey any information) should be explicitely silenced in code so that they are not read out by screen readers.

• Images that are completely redundant (meaning that convey information or functionality that’s already conveyed in text) should be explicitely silenced in code so that they are not read out by screen readers.

  • For example, if a magnifying glass icon is part of a button that has a visible label with the text “Search”, the image itself shouldn’t be read out by screen readers

Common mistakes

• The image communicates information but does not have a text description;
• The text description does not communicate the same information as the image;
• The image has a text description that is an exact duplication of content elsewhere on the page.

Why?

This ensures that information conveyed by non-text content is available to people who cannot see it, like screen reader users.

Official wording in the Web Content Accessibility Guidelines

1.1.1 Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below. (Level A)

• Controls, Input: If non-text content is a control or accepts user input, then it has a name that describes its purpose.

• Time-Based Media: If non-text content is time-based media, then text alternatives at least provide descriptive identification of the non-text content.

• Test: If non-text content is a test or exercise that would be invalid if presented in text, then text alternatives at least provide descriptive identification of the non-text content.

• Sensory: If non-text content is primarily intended to create a specific sensory experience, then text alternatives at least provide descriptive identification of the non-text content.

• CAPTCHA: If the purpose of non-text content is to confirm that content is being accessed by a person rather than a computer, then text alternatives that identify and describe the purpose of the non-text content are provided, and alternative forms of CAPTCHA using output modes for different types of sensory perception are provided to accommodate different disabilities.

• Decoration, Formatting, Invisible: If non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology.

See the W3C’s detailed explanation of this guideline with techniques and examples.

---

Guidance for Design

• Annotate your designs to tell developers what the text equivalent of images should be:
  • When the image conveys information (like an image that is part of a news article), the text description should convey the same information as the image.
  • When the purpose of the image is to convey a functionality (like a magnifying glass icon), the text description should convey that funtionality (like “search”).
• Annotate your designs to tell developers which images should be ‘silenced’ (ignored by screen readers) because they are purely decorative or completely redundant.
• Make sure that charts, graphs, diagrams and other complex images are described in text on the same page or in a page linked from the page containing the image.
  • When charts or graphs are used to display information that (that is, data with internal relationships that could naturally represented in a table), the same data is shown in a correctly marked-up table.
• Verbose alternatives make content harder to listen to and understand for screen reader users. Endeavour to be succinct, and avoid redundant phrasing such as “Picture of …”, “… logo”, or “Select this to …”.

This section needs one or more examples. Contribute or report issues via Github or email.

More guidance for design

• Alternative text tutorial by WebAIM explains how to write and set alternative text
• The Image concepts tutorial by the W3C Web Accessibility Initiative explains the different types of images (e.g. informative, functional, decorative) with examples
• W3C Alt text decision tree

---

Guidance for iOS

Giving a non-decorative UIImageView a label:

logoImageView.isAccessibilityElement = true
logoImageView.accessibilityLabel = "Company Name"

Hiding a decorative UIImageView from screen readers:

decorativeImageView.isAccessibilityElement = false

More guidance for iOS

• UIAccessibility developer reference

---

Guidance for Android

Giving a non-decorative ImageView a label:

Any ImageView, ImageButton, etc. that are non-decorative, must have a contentDescription set. AndroidStudio lint check will remind you with a warning if you skip it. Remember to place your strings in the res folder, so you can easily change them, translate them, etc.

<ImageView
  ...
  android:contentDescription="@string/company_name"
  ... />

Alternatively, you could set the contentDescription programatically:

imageView.importantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_YES //optional, because all views that are focusable are important for accessibility
imageView.contentDescription = getString(R.string.company_name)

Hiding a decorative ImageView from screen readers

In your XML Layout, set the contentDescription to @null.

<ImageView
  ...
  android:contentDescription="@null"
  ... />

This satisfies Android Studio’s lint check by confirming that you are not providing a contentDescription for this view intentionally, rather than forgetting to do so.

Do not add placeholder labels to dismiss lint warnings. If you leave these placeholder labels in your app when you publish it, your users might get confused.

Alternatively, you could hide the view from screen readers programatically:

imageView.importantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_NO

More guidance for Android

• Accessibility developer reference

---

Guidance for Web

All HTML images should have the alt attribute in their source code

• If an img or svg element doesn’t have an alt attribute, screen readers will read the file name of the image as it’s name;
• If you need to ‘silence’ an image, give it alt="".

For images that convey information, the alt text should convey the same information

• A meaningful and accurate textual description should be provided for all ‘informative images’ (meanings images that convey important information).

For images that convey functionality, the alt text should convey the same functionality

• A textual description of their function or destination content should be provided for all ‘functional images’ (meaning images that act as links or buttons).
• For example, a mignifying glass icon that triggers a search function should have alt="Search" (unless the image is accompanied by a “Search” text node, in which case the image should be silenced to avoid repetition).

Example

<img src="rating.jpg" alt="Rate this article" />

Failure example

<!-- Don't do this -->
<img src="rating.jpg" alt="Greyed out stars" />

Do not include the type of the element in its alt text

• Textual descriptions do not need to communicate the type of element (e.g. “image of”, “button for” do not need to be included).

Silence images that are purely decorative or completely redundant using alt=""

• Images that are ‘purely decorative’ (meaning images that have a solely decorative purpose) and images that are ‘completely redundant’ (meaning images whose meaning is already written in text) should have alt="", or be CSS background images, so that they’re ignored by screen readers.

Do not use CSS background-image for images unless they’re purely decorative or redundant

• Do not use a CSS background-image for images that convey purpose or information not already available in text. (CSS background images should only used for decorative images).
  • Here’s why:
    • Background images are not available to assistive technology such as screen readers and are not supported on devices with minimal support for CSS.
    • Additionally, a background image may not load.
    • It is not possible to directly assign alternative text to a CSS background image. Another method must also be used to provide the same information visibly, and in a way that is programmatically determinable by assistive technology, such as screen readers.

More guidance for Web

• Alternative text tutorial by WebAIM explains how to write and set alternative text
• The Image concepts tutorial by the W3C Web Accessibility Initiative explains the different types of images (e.g. informative, functional, decorative) with examples
• W3C Alt text decision tree
• Requirements for providing text to act as an alternative for images in the HTML 5.1 specification
• Why CSS background-image should not be used to include images that convey important information

---

More info

Sources

• W3C Web Content Accessibility Guidelines 2.1
• Government Digital Service WCAG 2.1 Primer
• Barclays’ Accessibility Design Standards
• The BBC’s Mobile Accessibility Guidelines

Contribute

This document is in beta. Help us by reporting issues via Github or email

This site is open source. Improve this page.