Image captions in WordPress: blocks, the Media Library and theme templates

Pages & images · Published 2026-10-03

Empty picture frames leaning against a brick wall next to a small table with a lamp — Empty frames against a brick wall, waiting for their pictures.

A caption is the visible line of text under an image. WordPress handles captions well today, but where you type one, and where it ends up, is less obvious than it looks.

This address once hosted the ShiftThis "Image Captions" plugin, written before WordPress had captions built in. It is discontinued and not available here. Captions have been a core feature since WordPress 2.6.

Caption, alt text, title, description

The Media Library offers four text fields for each image, and they do different jobs:

Field	Who sees it	Use it for
Alternative text	Screen-reader users, and everyone when the image fails to load; search engines	Describing what the image shows or does, in context
Caption	Every visitor, under the image	Context, credit, explanation
Title	Mostly no one; shown in the Media Library	Your own organisation
Description	Visitors on the attachment page, if your theme shows it	Longer notes about the file

A caption does not replace alt text. If the caption already describes the image fully, the alt text can be brief, but the two are read separately. The W3C's alt decision tree is a practical guide to writing alt text.

Adding a caption in the block editor

Select an Image block and type in the caption area directly beneath the image (if it is hidden, use the block toolbar's Add caption button). The caption is stored with that block, in that post only. It supports links and basic formatting, which is handy for crediting a photographer or a licence.

When you insert an image from the Media Library, WordPress pre-fills the block's caption with the caption saved on the attachment, if any. After that, the two are independent: editing the caption in the post does not change the Media Library, and vice versa. Gallery blocks work the same way, with a caption per image plus an optional caption for the whole gallery.

Captions in the Media Library

Open Media → Library, click an image, and fill in Caption. This is the place for a caption you want reused every time the image is inserted, such as a photo credit. For images that came from a camera, WordPress may pre-fill the caption or title from the file's embedded IPTC or EXIF metadata on upload, so check these fields before publishing. The fields are described in the WordPress.org article on the Media Library screen.

How captions are output

The Image block saves standard HTML:

<figure class="wp-block-image size-large">
  <img src="photo-1024x683.jpg" alt="Harbour at dawn">
  <figcaption class="wp-element-caption">Photo: A. Example</figcaption>
</figure>

The figure and figcaption pairing tells browsers and assistive technology that the caption belongs to the image. Posts written in the classic editor use the [caption] shortcode instead, which WordPress converts to similar markup when the page is displayed. Both keep working; converting old posts to blocks turns shortcode captions into Image blocks.

Styling captions

In a block theme, open Appearance → Editor → Styles, then the typography or elements settings for captions: changes there apply to every caption on the site, because WordPress gives them the shared wp-element-caption class. In theme.json the same setting lives under styles.elements.caption. In a classic theme, target the classes in CSS:

.wp-element-caption,
.wp-caption-text {
  font-size: .875rem;
  color: #555;
  text-align: center;
  margin-top: .5em;
}

Keep enough contrast between caption text and background; WCAG asks for a ratio of at least 4.5:1 for normal-size text.

Showing captions in templates

Featured images do not display a caption by default. In a block theme, the Post Featured Image block does not output the attachment caption on its own; a custom block or a small template change is needed. In PHP templates, get the caption of the featured image with get_the_post_thumbnail_caption(), or of any attachment with wp_get_attachment_caption():

if ( has_post_thumbnail() ) {
    echo '<figure class="hero">';
    the_post_thumbnail( 'large' );
    $caption = get_the_post_thumbnail_caption();
    if ( $caption ) {
        echo '<figcaption>' . wp_kses_post( $caption ) . '</figcaption>';
    }
    echo '</figure>';
}

Escaping with wp_kses_post() keeps links in the caption while removing unsafe markup.

Writing useful captions

Add information the image cannot carry on its own: who, where, when, or why it matters to the article.
Credit the source when the licence requires it. Creative Commons licences generally require attribution; the Creative Commons attribution guide shows the expected format.
Keep it short. A caption that repeats the paragraph next to it adds nothing.
Don't put essential instructions only in a caption; some readers skip them.

Troubleshooting

Caption shows in the editor but not on the site: the theme hides figcaption with CSS. Check the theme's stylesheet or customiser options.
Changing the Media Library caption doesn't update posts: expected; captions are copied into posts at insertion time. Edit the block.
Odd text appears as caption on upload: it comes from the image file's metadata. Clear it in the Media Library, or strip metadata before uploading.

Image captions in WordPress: blocks, the Media Library and theme templates

Caption, alt text, title, description

Adding a caption in the block editor

Captions in the Media Library

How captions are output

Styling captions

Showing captions in templates

Writing useful captions

Troubleshooting

Read next

Thumbnail and image sizes

Ordering pages

Sending a newsletter