Web Standards WordPress

Title, Caption, Alt Text, and Description: Harnessing the Power of WordPress Image Metadata

Images play an important role in web publishing, and WordPress makes it easy to add images to your content in several different ways. What you probably didn’t know is that taking a few extra minutes to fill in the “Attachment Details” for your images can improve their communicative value, create better user experiences for your visitors, and bring more people to your site.

In this article I’ll explain what the Title, Caption, Alt Text, and Description fields are all about and why they matter more than you think.

Every Image has its own Attachment Post

Screen grab of the Attachment Details fields in WordPress
The Attachment Details fields show up any time you add an image to a post or page

Let’s start at the beginning: When you add an image to WordPress, whether it be as a Featured Image (previously “post thumbnail”), an image in a post or page, or as a header image, you are actually creating a new Attachment Post. Once the image is added you can edit its Attachment Post by clicking the Media button in WordPress admin. This gives you a list of all the attachment posts associated with uploaded media items on the site.

Depending on your current theme you may also be able to access the Attachment Post page for the image from the front end of your site, and this attachment page may display some of or all of the meta data associated with the image.

Images and Attachment Posts can carry a lot of metadata

When you add a new image to a post you are prompted to add so-called “Attachment Details”. These attachment details are probably the most ignored and underutilized features of WordPress and if you learn what they are and how to use them you’ll never ignore them again:


The title is the only attachment detail required by WordPress. Title defaults to the name of the file but should be changed to a descriptive title of the image. This is the title of the Attachment Post for the image and just like a regular post the title will define the pretty permalink for the attachment post. You can also use the Title to search for images in your media archive.

In previous incarnations of WordPress the Title field was mapped to the optional HTML title attribute. This resulted in the title of the image appearing as a tooltip any time a mouse hovered over it. In the current incarnation of WordPress the title attribute for the image itself and also the optional image link are added separately. To do so you have to add the image to the post, then reopen it by selecting it and clicking the pen icon in the top left hand corner, and toggle the Advanced Options section of the Image Details modal window. Here you find Image Title Attribute as well as Image CSS Class (of which I spoke in a previous article), Open link in a new tab, Link rel, and Link CSS Class.

Screenshot of the advanced image options fields in WordPress
The Advanced Options under Image Details allow you to add title attributes to your images.


The caption is the text traditionally displayed underneath the image though the exact placement will vary depending on your theme. The caption is not tied to the attachment post but to where you choose to place the image in a post. That means if you use the same image in several different posts or several different places within a post you can have individual captions for each.

In WordPress captions are added using the shortcode which wraps around the <img> and optional <a> tags. This is why you can’t move images with captions in the visual editor but have to do it from the code end. For the image above the entire embed code complete with caption shortcode looks like this:

[caption id="attachment_2896" align="aligncenter" width="700"]
  <a href="" target="_blank" rel="attachment wp-att-2896">
      class="wp-image-2896 size-large" 
      title="Learn more about the Advanced Options for WordPress images" 
      alt="Screenshot of the advanced image options fields in WordPress" 
  The Advanced Options under Image Details allow you to add title attributes to your images.

It is worth noting that WordPress image captions can contain HTML including links.

Alt Text

The alt attribute or “Alt text” is mandatory for images on the web but is often ignored because it seems unnecessary. This is unfortunate because the alt attribute is both important and powerful.

The alt attribute is the text that displays when an image does not display. The general rule of thumb when applying alt text to an image is to describe in text what the image is communicating.

There are specific rules that govern how the alt attribute should be used:

  • If the image has communicative content (either says something or is illustrating something that has relevance to the content on the page) the alt text should describe the content either by repeating the text in the image or describing its content.
  • If the image is wrapped in a link the alt text should describe the target of the link.
  • If the image is purely for decoration and has no communicative value the alt tag can be left blank (alt=””)

People often think that the alt text is for visitors with accessibility problems. That is true, but it’s just part of the story: The alt text is there to describe image content and relate it to your overall content. While most visitors don’t see the alt text, search engines do and they index the images based on them. And as we move into a world of wearable devices that don’t always show images the alt text will become more important than ever before.

Bottom line: Always describe your images in the alt text field unless they are purely for decoration.


The Description field is probably the best kept secret of images in WordPress. If you add text to the description field that text will be stored as post content for the attachment post. That means if someone lands on the attachment post page for the image they will see the long description (provided the current theme supports it). To see how this works try clicking on one of the images in this article. You’ll be taken to the attachment page for that image where you see the image title, the image itself, the caption, and the description as post content. The attachment page in the theme I’ve built for this site also provides meta data that shows what post the image is associated with, a link to the original image size, and even navigation links to other images within the same post.

Once you’ve added an image to a post and you want to change or add to the Description you have to open the editor for the image Attachment Post. You can do that by going to Media in admin and finding the image or by navigating to the image on the front-end of your site and clicking Edit Media in the WordPress Toolbar. Though the Description field does not have the Visual (WYSIWYG) editor you can treat it exactly as you would any other post or page. It takes HTML and allows you to format the content to make it look like a regular post.

The Power of Metadata

Combined these text fields are a powerful feature that can be used to create better and more communicative experiences to your visitors and also bring new visitors to  your site. To see how let me give you an example:

Let’s imagine for the moment you are a wedding photographer and you are publishing a photo essay about a recent wedding. In the main post you add some images with basic captions and you describe these images with alt text that also includes your company name, words like “wedding photographer”, and the city you work in. When the post is published Google will index this alt text and people searching for wedding photographers in your city are likely to find your images during an image search.

You also add a standard WordPress image gallery to your post, but instead of using a lightbox to make the images “pop” up in the browser you redirect each image thumbnail to the respective attachment page for that image. Then when you add the images in you write a story for each of the images in the Description field.

Now when the visitor clicks on one of the images in the gallery she is taken to the attachment page where she gets to see a larger version of the image along with the added description. And again this description is indexed by Google. That means you can add the names of subjects in the images, detailed descriptions of products, services, locations, or the subject matter, or provide stories to go with each individual image for a truly unique experience. More than a boring image gallery you can create a photo essay – an immersive experience.

Another example of a good way of using these features is to share slides from a presentation. By adding the slides as individual images, adding comprehensive descriptions of each slide in the Description field, and linking your gallery to the attachment page you can provide far more information about your slides to your audience and make that information searchable on the web.

Start Using Your Attachment Details Today!

Now you understand what the attachment details are and how WordPress uses images and their metadata. The next step is to start using these fields actively to provide your visitors with better user experiences and get your content indexed in more places. I wasn’t joking when I said these are the most ignored and underutilized of WordPress’ features, and that also means if you start using them actively and getting the most out of them you will be way ahead of the competition. So what are you waiting for? Go set up proper titles, captions, alt texts, and descriptions for your images and report back!

Tutorials WordPress

Adding Borders to WordPress Images the Right Way – a.k.a. Why Inline Styles Have No Place In Your Posts

As with most updates to popular software the 3.9 release of WordPress has brought with it some controversy. In this case the point of contention is the removal of a little known feature that allowed the user to add borders and margins (vertical and horizontal “space”) to individual images right from within the image editor. The feature was removed and not surprisingly those that used and depended on it are enraged. WP Tavern has a great rundown of the story complete with links to forum posts so I’m not going to rehash it here. Instead I’ll show you how to add borders to images the right way, explain why inline styles are to be avoided whenever possible, and finally provide a suggestion on how theme developers can prevent this type of issue from happening again.

How to Add Borders to Individual Images the Right Way in WordPress

So, when you have an image, you want that image to have a border, and your theme doesn’t apply a border automatically, what do you do? You add some CSS. And that CSS needs to be added separately from the content. In other words no inline styles.

Depending on your level of skill this may or may not seem like a big deal. I’m here to tell you it’s actually super easy. Let’s say you know nothing about HTML or CSS or anything else. Here’s all you have to do:

  1. Install and activate Jetpack (the plugin)
  2. Go to Jetpack, find Custom CSS, and click the Customize button
  3. Create some new style rules

Customize CSS with Jetpack
Let’s say you want to add a black border. Here is the code required:

.border-black {
    border: #000 solid 1px;

Want a gray border instead? Here’s the code for that as well:

.border-gray {
    border: #b9b9b9 solid 1px;

With your new CSS rules in place you are ready to apply them to your image. To do so go to your post, find your image, click the edit button by hovering over that image, and in the edit window click the Advanced Options tab to open the Advanced Options.

Adding new CSS classes to images using the Advanced Image Option

From here all you have to do is enter the class name for your CSS rule (“border-black” for black, “border-gray” for gray) in the Image CSS Class field and save your image.

If you want to add multiple classes you can. Just separate them with a space. Also, remember to not put the dot (punctuation mark) in front of the class names. This is not necessary.

If you look at the image above you’ll see it has a black border. This border was added using the exact method described in this tutorial.

Edit: In the comments Caspar Hübinger points out you can also use the Simple Custom CSS plugin to add CSS to your site without adding all the bulk of Jetpack.


So what have we done here? First we created two new CSS rules that define a 1px border around any element that is either black or gray. Then we use the WordPress editor to apply those styles to our image through a class. And voila! The image has a border.

The key difference between this approach and that of adding the border with an inline style is that we can now quickly change the border on all images at once by editing the custom CSS. And since we used the Custom CSS function in Jetpack the border will persist even if we switch to a different theme.

Jetpack? You must be off your rocker Morten

At this point if you’re a seasoned WordPress pro you’re probably blowing a gasket over my recommendation of Jetpack. “Jetpack is huge and cumbersome and slows the site down and there are a million other better more awesome solutions etc etc etc.” And this is true. I am no fan of Jetpack. However we have to consider the end-user here: If  you are using the add image border function you probably do so because you don’t want to tamper with your theme or child theme. If that’s the case, Jetpack provides an easy way around the problem. Of course if you have the skills and the time you can add the exact same code to your child theme or custom theme you built from scratch, but this is not a workable solution for the majority of WordPress users. Jetpack is.

Inline Styles are Bad, Mmmmmkay?

Some will interject here and say that you can achieve the same thing by using inline styles. After all that’s what the old solution did and what the new Advanced Image Styles plugin does. Here’s some sobering web standards news: Inline styles is a non-starter. To understand why you need to understand how HTML and CSS interact and why inline styles have no place in WordPress content.

There are two main types of code that go together to create a website:

  • HTML
  • CSS

The HTML marks up the content and tells the browser or other reader how different parts of the content relate to each other. The CSS adds a presentational layer to that markup telling the browser or other reader how to display that content. This provides a clear separation between style and content and it works exceptionally well, especially in applications like WordPress where we can switch themes (and with them the CSS) of the content and see a global change in the appearance of the content without having to change the content itself.

Inline styles are an old leftover from the time when CSS was just being introduced and they work counter to the separation I explained earlier. An inline style allows you to place CSS code inside the tag of any element meaning that style only applies to this singular element. That’s what a function like add borders and space does: It puts presentational code inside the markup.

Why is this bad? There are many reasons:

  • The inline style will apply everywhere regardless of where you display the content.
  • The inline style overrides any CSS supplied by a stylesheet and interferes with media queries and other responsive approaches.
  • The inline style applies to one element only and cannot be easily repeated (ie it has to be applied to every single element).
  • The inline style does not allow us to make a global change to the style that applies to all elements at once.
  • The inline style is presentational code placed in the markup. This goes against current web standards and should be avoided.

There are very few cases where inline styles are appropriate. The only one I can think of is where you use PHP to inject a conditional background image into a specific element, but even there we have better ways of approaching the problem. Needless to say inline styles have no place in WordPress, and especially not in adding borders or margins to images.

But what about margins?

I’m sure you’re itching to point out that my proposed solution only addresses borders, not “space” or margins. And you’d be right. Of course you can use the same approach as before to add margins as well but I have serious reservations about this which I’ll explain in a few paragraphs. However, if you must tamper with the margins I’d make sure to add them as separate CSS rules. I’m willing to bet that if you are adding custom margins it is because the positioning of your images out of the box is not ideal. So essentially you are fixing a layout problem in the theme. Chances are you also add different margins depending on the image, but you tend to add the same set of margins over and over. In that case you create a new CSS rule for each of your margin scenarios and apply them as necessary the same way we applied the border.

As an example you could have this margin rule:

.margin-medium {
    margin: 0 1em 2em;

which adds a margin of 0px on top, 1em on left and right, and 2em on the bottom. Then to apply both the black border and the margin you simply enter “border-black margin-medium” in the Image CSS Class section for the image.

Now that you know how to do it I’m going to strongly recommend you don’t mess with the margins. This requires a bit more of an explanation:

The Problem

The problem at hand is not one of deprecated WordPress features nor of bad user behaviour. The cause of the outrage and frustration is that theme developers are not accounting for the user scenario where the user wants to add a border. When there is no option the user will find a new way of doing it outside of the theme and this is not ideal for anyone.

There are many reasons why you’d want to add a border. The most obvious one is if your image background color matches the color of your theme so there is no clear separation between the image and the main background. I’ve encountered this many times and this is why my themes ship with custom CSS to address this particular issue. More on that in a bit. Let’s first take a look at what happens when you add images to a post or page in WordPress:

When you add an image to a post or page in WordPress you also add some CSS classes to that image. The classes vary depending on the image size and alignment and other factors. A good theme has CSS rules that apply  to these classes and provide proper margin and padding for all images. And this is why messing with the margins is a bad idea:

In a good theme the designer and developer has made decisions about how an image is to be presented in relation to other content based on its size and alignment. That means margin has been added where required and removed where it shouldn’t be. If you go in and start adding or subtracting margins you are interfering with what the theme does out of the box and this can lead to crazy behaviour, especially when you switch to a new theme.

Here’s the thing: If your images jam up against text or other elements in your theme it is either the explicit decision of the theme developer that they do so or more likely the theme is not all it’s cracked up to be. Yep, I said it: If your images look wrong in context, your theme is likely not worth its salt and you should look for another one.

The Solution: A Unified Border Class Name Standard

There is an obvious solution to this issue that will allow users to do what they want (add borders to images) while ensuring cross-theme compatibility while avoiding the addition of plugin functionality like Jetpack Custom CSS or plugins that add inline styles: Create a unified border class name standard.

All theme developers should add a set of CSS rules targeting a pre-defined list of border classes the user can call when required. The list could look something like this:

.border-thin-black {
    border: #000 1px solid;

.border-medium-black {
    border: #000 3px solid;

.border-thick-black {
    border: #000 5px solid;

.border-thin-gray {
    border: #b9b9b9 1px solid;

.border-medium-gray {
    border: #b9b9b9 3px solid;

.border-thick-gray {
    border: #b9b9b9 5px solid;

In addition theme developers could make rules whose colors are set through the customizer with class names like .border-thin-custom. That way custom colors can be introduced as the user switches themes while the predefined colors stay intact.

Let your voice be heard

I know you have opinions on this. Don’t internalize your strife. Voice your thoughts, concerns, and opinions in the comments below and start a conversation.