WordPress & Web Development / Image accessibility / Practical guide
Write WordPress image alt text around what the image contributes to that particular page. Describe useful information, explain the destination or action of an image-only link, and use an empty alternative for an image that is purely decorative. Add or review the text in the page’s Image block, then check the published output rather than relying only on the Media Library field.
The goal is a useful text alternative, not a description of every visible detail. A short explanation of the image’s purpose is often more helpful than a long catalogue of colours, objects, and keywords.
Decide why the image is on this page
Begin with a question: what would a reader lose if this image were unavailable? The answer determines the alternative text more reliably than the filename or the article’s target keyword.
The W3C WAI alt decision tree distinguishes images that convey information, provide a function, repeat nearby content, or simply decorate the page. Apply that decision to each use of an image.
A photograph of a laptop could illustrate a connector location in a tutorial, show a product’s condition in a listing, or provide atmosphere behind a heading. The file may be identical, but the useful information changes with the context.
Finish this sentence first: “This image is here so the reader can understand…” If you cannot identify useful information or a function, consider whether it is decorative. If the answer requires several paragraphs, provide a fuller explanation in the page content.
This is an editorial judgement. An automated tool can flag a missing attribute, but it cannot reliably decide whether your description captures the reason you included the image.
Alt text, captions, titles, and descriptions do different jobs
WordPress’s Media Library documentation lists Alt Text, Title, Caption, and Description as separate attachment details. Filling one does not mean you have completed the others.
| Field | Main purpose | Editorial question |
|---|---|---|
| Alt text | Provides a text alternative for the image in its use on the page. | What information or function needs an alternative? |
| Caption | Adds a visible explanation alongside the image. | What context should everyone reading the page receive? |
| Media title | Names the media item; display depends on the site’s implementation. | Can editors identify the correct asset? |
| Description | Stores an explanation of the media item. | What additional attachment information is useful? |
Do not assume a caption automatically replaces the need to consider an alternative. Read the image, caption, and surrounding paragraph together. Avoid repeating the same sentence unnecessarily, while preserving information that would otherwise be lost.
The media title is also different from an HTML title attribute added to an image. Neither is a substitute for checking the image’s actual alternative text.
Describe the meaningful information, not every pixel
WAI’s guidance for informative images focuses on the meaning conveyed visually. A literal inventory is useful only when those visual details are part of the information the reader needs.
Hypothetical tutorial example: an image highlights the USB-C charging socket on the left side of a laptop. “Laptop on a wooden desk with a black cable” misses the instructional point. “USB-C charging port on the laptop’s left edge, beside the headphone socket” is useful if the pictured hardware actually shows that arrangement.
| Image context | Useful direction | Avoid |
|---|---|---|
| Product condition photo | Describe the visible defect relevant to the listing. | Claiming a condition that the photograph does not establish. |
| Tutorial detail | Identify the control, connection, or state being demonstrated. | Describing irrelevant background objects. |
| Team portrait | Identify the person when that identity matters to the page. | Guessing personal characteristics from appearance. |
| Conceptual illustration | Explain the relevant concept or visual content honestly. | Presenting an illustration as a real screenshot or measured result. |
These are writing examples, not descriptions of images tested for this guide. Always inspect the actual asset and its surrounding content before adopting wording.
WAI’s writing tips recommend a concise phrase or sentence and putting important information first. If the necessary explanation is long, move the detail into an accessible description in the page.
Google’s image SEO guidance also asks for useful, contextual alt text and warns against keyword stuffing. Use a topic term when it accurately belongs in the description; do not append a string of search phrases.
Use empty alt text deliberately, and describe image-only links
Purely decorative images
WAI’s decorative-image guidance uses an empty alternative, written as alt="", for images that add no information beyond their decorative role. Omitting the attribute is different: some screen readers may announce a filename instead.
<img src="section-divider.webp" alt="">Do not mark an image decorative simply because writing its description is difficult. If it contains an essential instruction, communicates a result, or is the only label for a control, it needs an appropriate alternative.
Images that act as links or buttons
For an image used alone as a link, describe the destination or purpose. WAI’s functional-image tutorial explains why the action matters more than the appearance of the icon.
<a href="/">
<img src="brand-logo.webp" alt="Example Company home">
</a>If the same link already includes clear visible text, the accompanying image may be redundant. Review the entire link rather than assigning a description to the icon in isolation.
Review the Image block and the Media Library separately
For an existing page in the block editor:
- Open the post or page and select the relevant Image block.
- Open its block settings and find the alternative-text control.
- Add context-appropriate text, or use the decorative option when appropriate.
- Save the page and verify the result on the public version.
WordPress’s Image block documentation explains that an alt-text edit in block settings applies to that specific page or post. Media Library alt text supplies a default when the image is inserted elsewhere.
Set a useful library default for reusable assets, but review each placement. A default cannot know that the same photo is informative in one article and decorative in another.
Editor labels and control locations can vary with the installed WordPress version and editor. If a page builder, gallery, featured-image template, or custom HTML renders the image, inspect that component’s settings and output too. Do not assume the Image block controls every image on the site.
For a reused asset, keep a short list of important placements to review. Changing one field is not proof that every existing page now contains the intended alternative.
Give charts and detailed screenshots a fuller explanation
A dense chart or workflow diagram cannot always be reduced to one useful sentence. WAI’s complex-image guidance recommends a short identifying alternative plus a longer textual representation of the essential information.
For a chart, include the key relationships and the values readers need in nearby text or an accessible table. For a process diagram, describe the sequence and decision points. Make that explanation available to everyone who needs it.
For a tutorial screenshot, ask what the reader is supposed to do. Explain the important control names and steps in real page text instead of making the screenshot the only source of instructions. Use the short alternative to identify the state or detail the screenshot demonstrates.
If a graphic contains essential wording that is not otherwise present, provide that wording in the alternative or accompanying accessible content as appropriate. Avoid forcing a long page of text into one attribute.
Check the rendered image, then review its usefulness
After saving, open the public page and inspect the image element in your browser’s developer tools. Confirm that the intended alt attribute is present. For a decorative image, check that it is empty rather than missing.
- Read the surrounding paragraph, caption, and alternative together.
- Check that the description matches the actual image and this placement.
- Check image-only links for a clear destination or action.
- Confirm that charts and detailed instructions have accessible supporting text.
- Review relevant mobile and template variants if they render a different image.
An automated accessibility check can help locate omissions, but a nonempty attribute can still be unhelpful or wrong. A manual content review and, where available, testing with assistive technology provide different evidence. Do not claim that an image is accessible solely because a scanner reports no missing alt text.
During the same page review, check whether important images also load promptly. Our Elementor hero-image and LCP guide covers image delivery and loading behaviour.
Frequently asked questions
Should every image have a written description?
Every image needs an appropriate treatment for its purpose. Informative and functional images need useful alternatives; purely decorative images generally use an empty alt attribute.
Can I reuse the same alt text everywhere?
Only when it remains appropriate to each placement. Review the image’s purpose and surrounding content rather than treating the library default as a universal description.
Is the caption the same as alt text?
No. A caption is visible page content. Alt text provides the image’s text alternative. Consider both together to avoid missing information and unnecessary repetition.
Should I add my focus keyphrase to every image?
Use words that accurately express the image’s purpose. Repeating an unrelated keyphrase makes the alternative less useful and can become keyword stuffing.
Choose one important page and review its images in context. Fix the alternatives in the component that renders them, save, and check the published result before expanding the review to more pages.
Sources and editorial notes
Official WordPress documentation, W3C WAI image tutorials, and Google Search Central guidance were checked in October 2026. Image scenarios and HTML are illustrative. This guide does not report a screen-reader audit of a live website.
Add comment