How To Write Alt Text and Why It Matters

How To Write Alt Text and Why It Matters

Alt text. We know it's something that can be added to images on the web, but what is it really? Who is it for? Why should we care? And, perhaps most important, how do we write it?

Let's explore these questions and more!

What is alt text?

Alt text, or "alternative text" as the long-form name suggests, is a written text description for an image on the web. It helps to describe the image for the reader to understand what the image is about.

In other words, alt text is content. And like any other content on your site, it should be well written and constructed, ready for consumption.

Why does alt text matter?

There are a few situations where writing alt text and including well formed descriptions for your imagery is beneficial for a successful website. Let's explore the various benefits of adding alt text.


When search engines, such as Google, crawl your site content, it indexes the alt text found embedded for all images found on the current page. This is used to gain a clear picture (no pun intended) of the content being served in order to provide accurate search results.

A common misconception is that alt text is only meant for SEO purposes, as a way to take advantage of the "hidden text" container and use it to try and increase site rankings among search engines. What's being described here is "Keyword stuffing" which is the act of using the alt attribute to inject as many "keywords" as possible in order to rank higher in search engine results. This action is greatly frowned upon and may actually lower your ranking. It could also be considered abuse as SEO is not the only reason to have alt text available, as we'll discover next.

For sighted users

If an image fails to load, potentially due to a poor connection or an underpowered device, the image's alt text is displayed on screen instead. This has the benefit of letting someone know an image was meant to load here, but as an alternative, they're still able to consume the text content.

For assistive technology users

Alt text provides people with visual impairments the ability to participate in consuming non-text content. When assistive technology, such as a screen reader, encounters an image on the web, the alt text is read and announced aloud. By doing so, someone who relies on this technology can still have a clear understanding of what the image represents.

People who use and rely on assistive technology have the most to gain when interacting with non-text content on the web, so it's imperative to set writing non-text content as a priority for your content authors.

How to write alt text

A woman sits behind an open laptop computer, facing another woman in mid discussion.

Writing high quality, descriptive alt text may not be as easy as it seems. A quick one-liner of "Cat on a couch," "white shoes," or "group of people," doesn't quite do the trick of painting a mental picture.

On the flip side, it is possible to overwhelm someone with too much descriptive text. Getting that fine line of descriptive precision is something of a skill master.

An exercise in describing images

The next time you need to write some alt text to describe an image, try this exercise:

  1. Pick a photo which requires alt text.
  2. Sit next to a colleague, friend, or family member.
  3. Without showing them the photo, describe out loud the image details.

    • If it's a group of people, describe where they are or what are they doing.
    • If it's a scenic sunset, describe how the sun might be beaming off the surrounding trees or buildings.
    • If it's an image of a product being sold, describe its physical features with enough detail in order for someone to consider making the purchase.'
  4. After you've described the image, show them the photo and ask them to compare what they pictured in their mind against the real thing.

In doing so, you'll have started the process of writing a description for the image. You might need to adjust and pair down the description appropriately for written content, but you're well on your way to adding helpful and useful alt text for your image.

An example

As a test, let's write some alt text for this image:

Dark blue, low-top shoes with a white midsole, brown lace, black back tab, and white lining.

 For this image, an accurate description might be something like:

"A pair of low-top shoes are placed on top of a dark-brown table in front of a white brick wall. The shoes are mostly dark blue with a white midsole, brown laces, a black back tab, and white lining."

This description is pretty accurate, but a little too wordy. Since we're describing a product we can focus directly on the product's physical features.

Let's cut the description back to just the essential, such as:

"Dark blue, low-top shoes with a white midsole, brown lace, black back tab, and white lining."

This alt text does the trick; it describes the image in a clear and precise manner, not overwhelming someone as they take in the content. The general recommendation is to keep alt text to around 100 characters in order to hit that fine line of "just enough" content.

Note: It's also worth pointing out that since image elements have their own semantic meaning announced by assistive technology, it's not necessary to include text such as "image of" or "graphic of" to describe an image – this will be announced automatically when the screen reader interacts with the image.

Does punctuation matter?

You may have noticed the use of punctuation in the alt text description of the image above. Does this make a difference in how the image description is conveyed to someone using a screen reader?

The simple answer is, yes. By using proper punctuation such as commas or period characters, this helps screen readers describe the image in more of a "human" sounding approach.

Commas will add a short break in between announcing content. Placing a period character at the end of a sentence will cause the screen reader to, "take a breath."

As with any well structured content, people who consume alt text using a screen reader also benefit greatly from proper sentence structure.

Images missing the alt attribute

A long-haired, grey and white cat with green eyes rests on a dark grey, fabric couch.

When writing HTML code, it's important to always include the alt attribute on an image element. Without this attribute, you risk running into some issues:

  • Without an alt attribute, your HTML markup is considered invalid and may result in an inconsistent user experience
  • When a screen reader encounters an img element without the alt attribute, the src attribute value is announced. This is often not helpful and can be regarded as a poor user experience.

With this in mind, whether you're working with Wordpress, React, or plain HTML, remember to always include the alt attribute when including an image in code.

The alt attribute in code: HTML

Adding alt text to an image when writing plain HTML is a matter of adding the alt attribute to an img element.

For example, the HTML for the above image would be:

  alt="A long-haired, grey and white cat with green eyes rests on a dark grey, fabric couch."

When this image is interacted with by a screen reader, the alt text will be announced helping to provide the mental model required to gain an understanding of the image content.

The alt attribute in code: Markdown

Markdown is a method to write and provide structured content for the web in a quick and easy manner.

How to create image content using Markdown is a matter of starting a new line of text with an exclamation mark, followed by a pair of square brackets which includes the alt text, then a pair of parentheses which includes the URL path to the image being served.

For example:

![A long-haired, grey and white cat with green eyes rests on a dark grey, fabric couch.](cat.jpg)

When the Markdown interpreter runs to convert this to HTML, it will look and behave the same way as the previous HTML example.

When to include alt text

You might be tempted to always include some sort of text within the alt attribute in order to cater to the cases outlined above. However, the fact remains that not every image should have a value set for its alt attribute.

How do we know when to include alt text for our images? Here are three common situations to consider if alt text should be added or if the alt attribute should be set as empty.

  • If the image itself contains text, such as a logo or an inspirational quote embedded within the image, the alt attribute value should be an exact match of the visible text.
  • If the image doesn't add any valuable content to the article or is adjacent to related text content, the alt attribute value should be left empty. This results in screen readers bypassing the image altogether as it is considered a "decorative" image.
  • If the image is considered to add content or value to the article, add descriptive alt text.
  • If the image is within a control, describe the control action, not the image.

There are more examples and situations to consider. For a more comprehensive list, check out the tutorial, "An alt Decision Tree".

Alt text in image maps

Image maps are a method to apply links, or clickable areas, to an image in HTML. These are usually used with infographic content in order to provide more information.

In the background, image map components are built with three HTML elements:

  • map – The wrapper element for each clickable section
  • area – The individual clickable area
  • img – The visual image to accompany the image map

We already know that an image in HTML requires the alt attribute and, conditionally, requires a text alternative to describe the image for screen reader users. The same concept is also true with image map area elements, which require the alt attribute in order to describe the clickable area to screen readers.

Social media

If you're running a social media account for your business, it's recommended to include alt text for images included. Let's look at a few platforms to see what they have available to help us be more inclusive and mindful of those who may not be able to see the imagery attached to posts.


Twitter has a built-in method to add alt text when attaching an image to a Tweet. This is a handy feature to be aware of and to use when attaching an image as without, a lot of folks might miss out on your great content!

The process to add alt text is documented in Twitter's help article, "How to make images accessible for people."


Facebook adds alt text to an image automatically after it's been uploaded. While the generated text can be mostly accurate, it's often not descriptive enough to paint that mental picture.

The process to override the auto-generated content is documented in Facebook's help article, "How do I edit the alternative text for a photo?"


Medium features its own method of adding alt text to images. Here's how to accomplish this:

  1. Set your article to Edit mode
  2. Mouse hover the image to highlight and then click the image
  3. Click the "Alt text" button
  4. Add your text alternative content

Note: when no alternative text is added to an image, Medium does not include the alt attribute which results in screen readers hearing the src attribute content! Be sure to include meaningful, non-decorative imagery in your posts.


Instagram also has a built-in method of adding alt text to its images. The steps to add alt text to your posts is outlined in the article, "How do I edit the alternative text for a photo on Instagram?"

Without specifying alt text, Instagram attempts to include an auto-generated description. Like Facebook, the automatic descriptions are fairly accurate, yet lack depth to truly describe the image.

If your platform of choice officially supports adding alt text to images, please remember to use these features whenever you upload a photo in order for everyone to take part and enjoy!

Also, remember to always include the alt attribute when embedding an image in your code or on social media. When appropriate, set its value to a descriptive and concise text alternative. This way you'll be creating inclusive content and everyone will be able to take part and enjoy the imagery in your posts!

WCAG success criteria

This comes back to 1.1.1 Non-text Content which states:

"All non-text content that is presented to the user has a text alternative that serves the equivalent purpose."


Back to blog