Press "Enter" to skip to content

How to Make Your Images Accessible

How to Make Your Images Accessible in WordPress

[series]Making your WordPress Theme Accessible Series:

  1. An Intro to Web Accessibility
  2. How to Organize Headings for Accessibility
  3. How to make your images accessible in WordPress ( We’re here now )



In the previous two installments of this accessibility series, I introduced web accessibility in general, and together, we went over organizing headings in our WordPress theme. In today’s post, we’re going to go over images. This post will cover what makes images accessible, and how we can apply those methods both in our theme templates and in our content. Let’s get started, shall we?

WordPress aside, how do we make images accessible?

We can do this by using the alt text (alternative text) on an image. In it’s simplest form, this is what alt looks like on an image. See my “The cake I baked today” example below:

<img src="my-cake.jpg" alt="The cake I baked today" />

But what’s it for? The alt text is used in the event that the image is not available or not visible. Some examples of this would be:

  1. A site taking too long to render all the images which then shows the alt text until the image is loaded.
  2. Email clients not displaying images by default.
  3. Accessibility technologies like screen-readers that “read” a site out loud versus visually displaying it. You can read more about how screen-readers work here.

Ok, mystery solved! Is that it?

No, not exactly. It turns out, and I’m just as guilty of this, that not only are people failing to use alt text on their images, but there’s also some skill involved in learning to write alt text effectively. After reading through some other sources, Describing your images for better web accessibility, Harnessing the power of WordPress Metadata, and the WordPress’ accessibility page, I rounded up a few tips for writing alt tags.

Rules for writing ALT attributes:

  • If the image is just for decorative purposes, you do not need to fill in the alt text. If someone can understand your content without the image – then the image is decorative.
  • Alt text should be short and to the point. Alt text that is too long can get cut off by some screen-readers. So to avoid that as much as possible, keep your alt text as short and to be point as you can.
  • Alt text is not the name of the image file.
  • Alt text is not just a repeat of your content title for “SEO purposes”. Remember the first item on this  list – is it decorative?
  • The WordPress caption and the alt text should not be the same. Alternative text is strictly to describe the image whereas a caption has less limits and can be for whatever you want e.g. photo credits, funny comment, and so on.
  • If your image has text, the alt should repeat that same text.
  • Titles are optional. Alt text is required for accessibility. These two should not be repeats of one another either.
  • Write alt text in context where it’s appropriate. Here’s the explanation copied from the WordPress Codex:When you include a graphic or photograph, it may be appropriate to provide an alternative description in the alt part of the tag. This description will be used in place of the image.
    ...and the most wonderful thing appeared: <img scr="ball.jpg" alt="a beautiful red and blue ball" />.

    Those who rely on screen reading software might hear, “and the most wonderful thing appeared: image – a beautiful red and blue ball.”

    In some cases the image is purely decorative. In these cases an alternative description is not necessary. You should always include the alt attribute, but in these cases, you can simply leave it empty.

    ...and the ball bounced higher and higher 
    as <img scr="ball.jpg" alt="" /> the child bounced it...

    Those who rely on screen readers might hear, “and the ball bounced higher and higher as the child bounced it.”

How do we use ALT in our WordPress Theme/Content?

Now this is where we get we’ve got to roll up our sleeves and get that elbow grease in. Judging by the TwentyThirteen theme right out of the box – themes don’t normally come with images that are not decorative. And therefore, if they’re decorative, then there’s no need to worry about alt text.

The only possible reason I can think of for a theme to have an image that is not decorative, would be the logo. Check your logo in your header.php and ensure that if it’s using a background image – it still has the H1 with real text in it.

Images that convey information should not be defined as background images unless a text equivalent is provided in the HTML code… ( source )

See below in TwentyThirteen? See how it has an H1 wrapping the site title using get_bloginfo? That’s what you want to keep.

<a class="home-link" href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
<h1 class="site-title"><?php bloginfo( 'name' ); ?></h1>

If your logo is a literal image src tag, make sure you add the alt with your company/site name. For WordPress, you can take advantage of the get_bloginfo() function to display the title of your site that’s set on your dashboard’s Settings > General section. See an example below.

<a class="home-link" href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
<h1><img src="<?php echo get_template_directory_uri() . '/images/my-logo.jpg'?>" alt="<?php bloginfo( 'name' ); ?>"/></h1>

Great. Now what we’ve covered the theme, what about all the images in our site content? We can do this in one of two ways.

  1. Upload images as we would normally in WordPress, and only worry about filling in the alt text when we’re inserting images into a post/page with the “Add Media” button.
  2. Go straight to the Media Library, and just go through each image one by one to check their alt text fields. This is a lot easier in WordPress 4.0 with the updated Media Library.

With the first method, this only works if you’re so disciplined, you never forget to fill in the correct fields every time you insert media into a post. This method is also only ideal for new posts/pages you’re writing on the fly, not for fixing your old ones or else you’ll have to go into each individually to edit them – that could take a while…

The second method is my preferred method for correcting my current blog’s theme now. To avoid editing each post individually, I can do it all from the Media Library, and even see what posts/pages the image was used on if it helps me fill out the alt text field. You can see what post/page the image was used on towards the bottom of the fields beneath Description, it will say “Uploaded To”. ( see screenshot below )

Screenshot of attachment details in the Media Library
What the attachment details look like in the media library once you’ve clicked on an image. Notice the “Uploaded To” area towards the bottom right.

How WordPress Behaves When the ALT is Left Blank:

I noticed a pattern in WordPress when it came to uploading images and I couldn’t find any confirmed resources online to prove that this is how WordPress functions out of the box. However, from my experiments, it looks like the ALT text will pre-fill itself depending on what other fields are filled in from the attachment details. Here is what I observed below:

  • Image without any fields filled in at all = Alt copies the image file name
  • Image without any fields filled in is added to a post/page = Alt replaces the image file name with the post/page title instead.
  • Image with only a title filled in = Alt will copy the title. This is the image title attribute, not a post/page title.
  • Image with a caption in a post/page = Alt will copy the caption text.

So the lesson learned from this is if I’m going to faithfully and correctly fill in alt text, I should not let WordPress be responsible for filling it in on it’s own unless in some cases, it might be appropriate.

And We’re Done!

That wasn’t so bad. We went over what the alternative text/alt  text is used for on images, how to best write alt text in general, and how to apply what we learned when editing our theme’s images. We also learned how WordPress will pre-fill the alternative text depending on what other fields are filled in the attachment details.

I once heard that it takes doing something 66 times to make a habit. I’m still fighting to ingrain this into my developer senses ( yeah like spidey sense, it’s totally a thing ) and I’m hoping the more I fill in alt text, eventually it’ll just happen naturally the way I’ve memorized the CSS shorthand for margin or padding. It’s not an easy habit to develop I think, but for the sake of making my WordPress theme just a bit more accessible, it’s a habit worth learning.

I hope that this post helped you. I’ll keep at it myself. Let me know if you have any suggestions or methods that have been working for you. I’d love to hear about it! 🙂


  1. Harshal Limaye
    Harshal Limaye November 7, 2014

    Hey Rachel,

    Really great post! 🙂

    Question: What is the purpose of image description? I have never been clear on If/where/how that comes into play?

    • RachieVee
      RachieVee November 18, 2014

      Hi Harshal,

      Thanks for reading! According to one of the articles I referenced, the description is used as content for the post attachment detail page. So you know when you “view image” in the attachment details on the dashboard or let WordPress link the image for the front-end, it takes you to the image by itself? Since attachments are a post type – the description serves as that post’s “content”.

      For more elaboration, check this out:

      Hope that helps and thanks for the visit. 🙂

  2. Alice
    Alice November 20, 2014

    Many thanks for this, Rachel.

    I’m always banging on about the importance of alt text but this is the first article I’ve found which explains it all in such a non-geeky way (I might even refer a few of my clients here…)

    Great references for further reading too. Thanks!

    • RachieVee
      RachieVee November 20, 2014

      Hi Alice,

      Happy it helps! Non-geeky is what I’m aiming for. Thanks for the comment. 🙂

    • RachieVee
      RachieVee December 17, 2014

      Oh snap, look who it is! *waving* Hi! And thanks, happy you enjoyed it. 🙂

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: