Skip to main content

Writing principles for alt text

Alternative (alt) text is written copy that provides information about images so that visual content is accessible to users even when it isn’t displayed or can’t be seen. You can add alt text to images through HTML code or by filling in the relevant fields in a content management system (CMS) or other software.

note

Alt text is separate from image captions, which are displayed at all times. Captions help users relate images to the surrounding text and can provide additional information, such as image attribution.

Providing effective alt text for images has the following benefits:

  • It promotes web accessibility for all users.
  • It allows screen readers to describe images for users with visual impairments and cognitive disabilities.
  • It provides descriptions of missing visual content when image files fail to load.
  • It helps search engine crawlers index and rank images in search results by providing descriptions and contextual information.

Alt text is especially important for accessibility because it allows users to interact with your content in different ways. For example, users with low vision often deactivate images and instead use assistive technology such as screen readers to read descriptions in alt text. Some users with cognitive impairments also find it easier to interpret text than visual content.

tip

The number of users who benefit from accessibility features like alt text is significant. According to the World Health Organization, about 16% of the world's population has some form of significant disability.

Best practices for writing alt text​

In general, follow these best practices for writing accurate and effective alt text:

  • Describe only relevant information.
  • Be succinct.
  • Use consistent language and punctuation.
  • Include all necessary information in the main text.

Describe only relevant information​

  • Describe only images that perform a function or are essential to understanding the text.
  • Describe the content and function of the image in context. What about the image is relevant to the text?
  • Don't include phrases like “Image of” or “Photo of” unless it’s important in context. Screen readers tell the user when they encounter an image.
  • Don't describe visual cues like callout boxes, because these cues aren't meaningful to the reader. Instead, focus on the information that is being highlighted.
  • For images of people, don’t include demographic information unless it’s relevant in context.
  • Whenever possible, don't repeat the image caption in the alt text. Screen readers read out both the alt text and image caption. Some platforms, such as the core user manual, automatically use the same text for both the alt text and image caption.

Be succinct​

  • Write short, descriptive alt text in 300 characters or less.
  • For simple images of objects or people that don't require additional context, describe the image in a few words. For example, a person's name and title, or the name of an object.
  • For complex images that require a long alt text description, use full sentences.
  • If the image presents more useful information than you can fit in the 300 character limit, include a brief summary of the image in the alt attribute, and then include a more extensive description of the image in the main body of the content.

Use consistent language and punctuation​

  • Use consistent alt text for repeated instances of an image, such as controls, status indicators, or icons that appear multiple times in your document.
  • Include punctuation. When screen readers encounter punctuation, they pause before continuing.
  • Use end punctuation, generally a period.
  • When possible, avoid using all-caps in alt text. Some screen readers read capital letters as each letter individually.
  • Don't use emojis in technical documentation. In social media content, limit or avoid the use of emojis. Screen readers read out emoji titles along with the text.

Include all necessary information in the main text​

  • Introduce diagrams in the text, not in the alt text.
  • Don’t include new information in the alt text.
  • Ensure that all information necessary to understand the topic is included in the main body of the content.