← Back to Blog

Alternative Text, Captions, Titles and Descriptions

Use the correct WordPress image text field for accessibility, visible context, management and attachment content.

Veyra Admin

5 min read

  • Guide
  • Beginner
  • 5 minutes read
  • Reviewed August 5, 2026
  • WordPress media

WordPress provides several text fields for media, but they do not serve the same purpose.

Using every field as an SEO keyword container creates poor accessibility and confusing editorial data. Write each field according to its actual function.

Alternative Text

Alternative text communicates the meaning or function of an image when it cannot be perceived visually.

Good alt text depends on context. The same photograph may need different text in a news story, a product selector or a decorative layout.

Use alt text when the image conveys information or performs an action. Describe the relevant meaning concisely rather than listing every visible detail.

Decorative Images

A decorative image should normally have empty alternative text so assistive technology can ignore it.

Empty alt text is different from a missing alt attribute. WordPress blocks and themes should output an appropriate empty attribute for decorative images.

Do not describe borders, spacer graphics or purely atmospheric imagery unless they contribute meaningful information.

Functional Images

When an image is inside a link or button, its alternative text should communicate the action or destination.

For example, a logo linked to the home page may use the site name or “Home” according to the surrounding context. Repeating nearby link text can create redundancy.

Captions

A caption is visible text displayed with the media. It can provide:

  • Credit or attribution.
  • Location and date.
  • Additional explanation.
  • A label for a figure.
  • Context that should be available to all readers.

A caption does not replace alt text. Sighted users may need the caption while screen-reader users still need an appropriate alternative for the image itself.

Attachment Title

The attachment title identifies the media item inside WordPress and may also appear publicly in galleries, attachment pages or theme output.

WordPress can derive it from the filename or embedded metadata. Review generated titles instead of assuming they are suitable.

A useful title helps editors find the asset, but it should not be relied upon as the accessible name of the image.

Description

The description is longer attachment content. Depending on the theme, it may appear on an attachment page. Many websites do not display it by default.

Use it when a fuller explanation, transcript, credit record or asset note is genuinely needed. Do not assume that visitors will see it unless the template displays it.

Instance-Level Context

WordPress stores alt text with the attachment, but an image block can require different wording in a specific context.

A central default is useful, yet editorial review should consider each placement. If the same image conveys different information in two articles, the alternatives may need to differ.

Filenames Are Not Alt Text

A descriptive filename helps asset management and URLs, but screen readers need actual alternative text in the page markup.

Similarly, a title attribute is not a reliable substitute for alt text and often provides a poor interaction experience.

Writing Checklist

Ask:

  1. Does the image convey information?
  2. Is that information already stated nearby?
  3. Is the image a link or control?
  4. Would an empty alternative be more appropriate?
  5. Does a visible caption provide necessary credit or context?
  6. Could the attachment title or description appear publicly?

Frequently Asked Questions

Should every image have descriptive alt text?

No. Decorative images should usually have an empty alternative.

Does a caption replace alt text?

No. They serve different audiences and purposes.

Should alt text contain SEO keywords?

Write for the image's meaning and function. Relevant terminology may occur naturally, but keyword stuffing reduces quality.

Applying Alternative Text, Captions, Titles and Descriptions in a Real WordPress Project

Consider the source asset, WordPress attachment record, generated files and every public use of the media. Accessibility, licensing, storage, performance and deletion safety should be reviewed together.

A connected concept is Alternative Text for Images. Reading the two together helps separate the immediate task from the wider WordPress responsibility.

A useful implementation begins by writing down the current state, the intended outcome and the evidence that will prove the change worked. This prevents a configuration screen, plugin recommendation or code snippet from becoming the entire strategy.

A Practical Example

Imagine a team making this decision for a production WordPress site. The useful question is not only “Can WordPress do this?” but “Which layer owns it, who maintains it, what data does it affect and how will we verify it after an update?”

Write the answer in operational terms. Name the content, user, setting, file, API or service involved. Then identify what should remain true if the theme changes, a plugin is replaced or the site is migrated.

Questions to Ask

  • What user or system problem does this solve?
  • Which WordPress layer owns the behaviour?
  • What data is created or changed?
  • Who may perform the action?
  • What can fail, and how will that failure be visible?
  • How is the result tested after updates?
  • What is the migration or removal path?

Combine Automated and Manual Testing

Automated tools are useful for repeated checks, but they cannot confirm whether alternative text is meaningful, focus moves logically or instructions are understandable.

Use automated scans as a baseline, then complete the real task with keyboard, zoom and assistive technology. Record the user impact, not only the rule number.

Diagnose the Bottleneck Before Optimising

A slow page can be limited by server response, database work, third-party scripts, rendering, media or interaction code. The same score can hide very different causes.

Capture a baseline, inspect the waterfall and main-thread work, change one layer and repeat the measurement. Keep a record of the tested URL, device, network profile, cache state and date.

Official Reference Context

The Web Content Accessibility Guidelines 2.2 is the primary version-specific reference for this topic. Use the current documentation to verify interface labels, supported APIs and behaviour before applying instructions to a production site.

How to Verify the Result

  • Check the original file, generated sizes and frontend delivery.
  • Verify alternative text, captions, credits and direct-file visibility.
  • Search for references before replacing or deleting the attachment.

Sources and Further Reading

Continue Learning