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:


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.


Complex images

Purely decorative and redundant images

Common mistakes


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)

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

Guidance for Design

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

More guidance for design

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

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.

  ... />

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.

  ... />

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

Guidance for Web

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

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

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


<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

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

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

More guidance for Web

More info



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