How to write and check alt text in WordPress
A useful description starts with what the image adds to the page. This guide takes you from a draft to a check of the actual image your visitors receive.
Write for the image’s purpose
For an informative photograph, explain the detail a reader needs in this context. A decorative image usually needs an empty alt="". If an image is the only content of a link, communicate its destination or action. Put a chart’s detailed information in nearby text or a table, with a short alternative identifying the chart. The W3C image decision tree helps with these choices.
Start with the subject and the relevant action or distinguishing feature. Remove details that do not help the reader. Do not guess someone’s name, a venue, a product model or text you cannot read. Verify those details against the project information before adding them.
A filename such as DSC_2048.jpg identifies a file; it does not explain a photograph. A list of search phrases also fails that job. Use a product name or location when it is accurate and useful in the image’s context.
Alt-text examples for photos and products
These are illustrative drafts for the situations described. The right wording changes with the actual photo and the surrounding page.
A photographer’s ceremony gallery
Image and context: A wide photo shows a couple exchanging rings beneath a wooden arch.
Draft: “A couple exchange rings beneath a wooden arch as guests watch.”
The ceremony moment distinguishes this image from the portraits beside it. Add verified names only when the gallery context calls for them.
A WooCommerce product detail
Image and context: A close-up shows the inside pocket of a navy canvas tote.
Draft: “Inside the navy canvas tote, showing its zippered pocket.”
This describes the feature shown by this particular view. Repeating the product title for every detail image would lose that information.
A room-booking website
Image and context: A room listing shows round tables with clear aisles between them.
Draft: “Round tables arranged with wide aisles in the event room.”
Do not infer the legal capacity, exact dimensions or an accessibility certification from the photograph.
How to check if an image has alt text
- Open the published page. Use a signed-out or private browser window. Checking a library record alone does not confirm what the page renders.
- Inspect the image. Right-click it and choose Inspect. Find the image’s
<img>element and itsaltattribute. A browser tooltip is not a reliable alt-text check. - Read the value in context. A missing attribute and an empty
alt=""are different. An empty value can be intentional for decoration; it needs review when the image carries information. - Correct the source used by the page. In WordPress, review the image’s Media Library details and the Image block’s alt-text setting. Page builders may have their own field. See the WordPress Image block documentation.
- Save, clear the relevant page cache and inspect again. Existing blocks can retain their own text after a library change. Recheck the live HTML, including any separate mobile image.
When an image acts as a link or button, also check the control’s accessible name in your browser’s accessibility panel. Background images do not have an alt attribute; meaningful information needs an accessible equivalent in the page content.
Review a batch of AI descriptions in AltWiz
Start with a small, representative set from the shoot or product catalog. Check close-ups, group scenes and images containing text before applying the same review process to a larger batch.
- Upload your exported images and let the background descriptions finish. Keep an eye on pending or failed items; retry a failed upload individually.
- Group related files into a collection. Open each image to review the draft against what is actually visible.
- Correct names and other project-specific details. Remove invented information and unnecessary repetition.
- Approve the descriptions you have checked, then sync to WordPress using your chosen manual or automatic workflow.
- Use the published-page check above on the pages that receive those images.
AI descriptions help with the drafting work. They cannot determine every image’s role on a future page, and alt text alone does not make an entire website accessible. The W3C guidance on informative images explains why the surrounding content matters.
