Digital Accessibility Fundamentals: Alternative Text

Text alternatives are needed for non-text media to make the media accessible. For images, this is called alternative text, or alt text for short. Alt text can be added to images just about anywhere they exist digitally. Find out how to write alt text, and add it to images in documents, Mass.gov, and HTML.

Alternative text for images

 

While they say a picture is worth a thousand words, if you can't see the image, it's only as good as its text alternative (alt text). Alt text can be added to an image in Office documents, PDFs, Mass.gov, emails, social media, and HTML.

When a screen reader user navigates to an image, the screen reader software will announce the description provided in the alt text. If you do not provide alt text, it will instead announce the image file name, which is unhelpful. It's important that every meaningful image has alt text. What that alt text is might be different depending on the purpose of the image.

Requirements in brief

• Graphics with meaning should have alt text
• Alt text should be 1 to 2 sentences at most
• Don't add "image" to the description, that is announced by default
• Decorative graphics should be marked as decorative or null in HTML ("")
• Video requires text alternatives (Learn more about accessible video - Link coming soon)
• Charts may need alt text or long descriptions (Learn more about data visualization - link coming soon)

How to write alt text

When writing alt text, it can be helpful to ask yourself four questions: 

• Does the image tell a story that is related to my content? 
• Is the image literal and necessary to understand my content? 
• Is the image functional? 
• Does the image have any meaning at all?

If an image tells a story, it makes sense to write alt text in that context, where you describe the image concept instead of the specific contents. If an image is a screenshot in a tutorial, the alt text should be more literal and exact. If the image is functional, then it's better to describe its function rather than how it looks. And if an image is simply decorative, it should be marked that way. Let's look at a few examples.

Story: If used on an Economic Assistance page to tell a story, the alt text might be "A concerned middle-aged man looks down at a desk full of bills and financial documents." 

Literal: If used in a tutorial, this screenshot would need a literal description like "The mass.gov CMS text editor with the Paragraph styles dropdown in the toolbar highlighted."

Functional: The icons in this image represent links to Facebook, X, LinkedIn and Youtube. Those icons should have alt text announcing the social media site, not describing the look of the logo.

Decorative: This background image of a lighthouse should be marked as decorative. Describing background images can make listening with a screen reader unnecessarily verbose.

A note about decorative images

While it's possible to mark images as decorative, it is not often the right way to go. Most of the time, if you include an illustration or photo, you are doing it for a reason besides decoration. Plan to write text for all images like this.

If the graphic is simply a shape, texture, flourish, pattern or background, then that is likely the appropriate time to mark it as decorative. If text exists with the image that would make alt text redundant, such as a silhouette icon with "profile" or "account" paired with it, like you'd find on many sites when logged in, that is also a time when an image should be marked as decorative.

How do I add alt text?

Techniques for adding alt text will vary depending on whether you are making a document, a page on Mass.gov, or an HTML web page.

Adding alt text to an Office document or Outlook email

In Word, PowerPoint or Excel, if you do not add text to an image, the app will attempt to automatically add alt text. Most of the time this text is wildly inaccurate, or too generic to be helpful. Be sure to add your own alt text, or mark it as decorative.

1. Right click an image in your document
2. Select View Alt Text...
3. In the Alt Text Panel, type in a description
4. If the image is decorative, select the Mark as decorative (not available in outlook)

Learn more about accessible Word documents

Adding alt text to a PDF in Acrobat

If you need to make changes to an existing PDF, you can do so in Adobe Acrobat Pro. 

1. Navigate to Tools > Accessibility
2. Choose Add Tags to Document
3. Select the image
4. Right click the image
5. Choose Edit Alternate Text, and enter your text in the box that appears

Learn more about making PDFs accessible with Acrobat (Link coming soon)

Adding alt text to a page on Mass.gov

When you upload an image to Mass.gov, you will be prompted with a box for alt text. Be sure to add alt text to this box. If you don't one of two things may happen depending on where you are adding your image.

1. It may be marked as decorative and skipped completely
2. It may be left blank and announce as the file name

Learn more about adding alt text to an image in Mass.gov

Adding alt text in HTML

Within an <img> tag, you can use the alt attribute. This might look something like this:

   <img src="/image.jpg" alt="One to two sentence description of the image." />

If the image is purely decorative, and you want to tell a screen reader to skip it completely, use a null like this:

   <img src="/image.jpg" alt="" />

Learn more about HTML accessibility  (Link coming soon)

Alt text equivalents on mobile apps 

If you are developing a mobile web page, or a hybrid app, alt text is still appropriate to include on images. However, if you are developing a native mobile app, both iOS and Android provide similar functionality with different terms.

On iOS, screen reader text for images and icons is provided via the accessibilityLabel.

On Android, screen reader text is provided via the content label.

Next steps

Explore more accessibility fundamentals