Alternative text for images, SVGs and icons in development

When an image has meaning or adds information on a page, that image needs a text alternative. Screen r`eaders will announce that alternative text, so visitors using assistive technology 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 good alt text and add them to 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 alt attribute to an img element. The alt attribute can:

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

When the alt attribute is not present, a screen reader may announce the filename or other information instead. Blind users will miss 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). Here are three valid options:

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> doesn’t render as visual text, 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 to explicitly connect the svg to its name:

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, to the accessible name of the link. Make sure the link text still makes sense.

If an image of, for example, a logo also contains text, like a byline, make sure that text is also added to the link text. Then no information gets lost.

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 of a website needs more information than just the link target. It must also show 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: There are regional differences on how to interpret the WCAG success criterion 2.4.4 Link Purpose (In Context) in this case. Please consult your accessibility expert on their opinion about what the accessible name of a link to home on a logo in the header should be.

Icons

Make sure screen readers users also know what’s shown in 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 a button, containing only 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>

The best option is to add visible text. An icon alone may not be universally understood.

<!-- 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 meaningful images proper alternative text, you meet WCAG success criteria:

Other resources