Alternative text for images, SVGs and icons in development

When a user can not see an image and that image has meaning, adds information, that image needs an alternative in text. Screen readers will announce that alternative text, so visitors that can not see the image will also know what it shows and won’t miss information.

You may think that you’re not including any images in your project. Possibly this is true; but are you using dashicons or other icon fonts? Are you using SVG graphics? For accessibility, “images” doesn’t only refer to the img element. It means any non-text graphical elements on the page.

All of these images require accessibility considerations. The W3C offers a useful decision tree to help you decide what kind of text you need for an image. If your image is conveying information or activating a control, it’s going to need some form of accessible name.

This page addresses the alternative text and accessible names for images in development. How to write a good alt text and add them in the content is addressed in the “Content and Images” section Alternative text for images in the content of this documentation.

Alternative text on an img

Always add the img attribute to an img element. The alt attribute can:

  • contain the alternative text, this will be announced by a screen reader
  • be empty, the image will be omitted by a screen reader.

When the alt attribute is not present, the screen reader will announce the filename instead. Blind users miss the information that is on the image.

Don’t: Remove the alt attribute

<!-- Do not copy,this is incorrect code -->
<img src="IMG_123.jpg">

Will be announced in VoiceOver as “IMG_123, image”.

Do: Add an alt attribute, describing the purpose of the image.

<img src="IMG_123.jpg" alt="All T-shirts are on sale">

Will be announced in VoiceOver as “All T-shirts are on sale, image”.

Alternative text on an svg

Tip: Carie Fisher published extensive research on how to create accessible SVGs.

For accessibility: add role="img" to an SVG that serves as an image. Then the element is recognized and announced as an image by screen readers.

There are several ways to give an SVG an alt text (an accessible name). We name 3, all are valid.

1: Use the attribute aria-label:

<svg aria-label="WordPress logo" role="img">
    [...]
</svg>

2: Use the element <title>:

WordPress logo 
<svg role="img">
    <title>WordPress logo</title>
    [...]
</svg>

The content of <title> isn’t displayed but browsers usually show the <title> as a tooltip.

3: Assign the accessible name to the content of <title> of the SVG, using aria-labelledby:

WordPress logo 
<svg aria-labelledby="titleID" role="img">
    <title id="titleID">WordPress logo</title>
    [...]
</svg>

The value aria-labelledby points to the id of the title.

When adding an image inside a link, the alt text will be added to the link text. Make sure the link text still makes sense. Repeat text that is visible in the image, also in the link text.

For example when you create a link to Instagram, showing only the icon.

<a href="[some-url]">
    <img src="logo-insta.png" alt="Instagram">
</a>

“Instagram” will be the link text, the accessible name of the link, announced by a screen reader when the link gets focus. So, in this case don’t add the word “Logo”, even if it’s a logo. Describe the link target.

The alt text on a logo in the header od a website needs more than just the target, also the fact that the image displays the logo of the website/company.

For example:

<a href="/">
    <img src="logo.png" alt="Company name logo, to the homepage">
</a>

Read the full explanation:

Please note: In the EU, this way of adding an alt text to the logo in the header is required to pass WCAG 2.2 AA. In other parts of the world only adding the link target may be sufficient to pass an audit. Ask your local accessibility auditor for advice in this case.

Icons

Make sure screen readers users also know what’s on the icon, if you use it in a meaningful way. This is particularly crucial if you’re using images to represent controls, like a hamburger menu icon, an arrow, or a plus or minus icon. These images are used to represent information.

For example, if you use a close button with an “X”-icon, make sure that button is announced by a screen reader as “Close”.

Examples for icons

Don’t Forget giving button with a menu icon an accessible name.

<!-- 
Do not copy,this is incorrect code.
This button has no accessible name and 
is announced just as "Button" by a screen reader. 
-->
<button>
    <span class="dashicons dashicons-menu"></span>
</button>

Do: Provide an accessible name to the button.

Use an aria-label on the button, this will be the accessible name.

<!-- This button is announced as "menu" by a screen reader. -->
<button aria-label="Menu">
    <span class="dashicons dashicons-menu"></span>
</button>

Add text, hidden from sight but announced by a screenreader using the CSS class .screen-reader-text.

<!-- This button is announced as "menu" by a screen reader. -->
<button>
    <span class="dashicons dashicons-menu"></span>
    <span class="screen-reader-text">Menu</span>
</button>

Or, the best option: add visible text. Because not everyone understands an icon.

<!-- This button is announced as "menu" by a screen reader. -->
<button>
    <span class="dashicons dashicons-menu"></span>
    <span>Menu</span>
</button>

Resources

Related WCAG Success Criteria for alternative text for images

By giving a meaningful image a proper alternative text, you meet WCAG success criteria

Other resources