Image alt text:
write and check it

Check what the image means, not just whether a field is filled in

Alt text is an image’s text alternative in a specific place on a page. It helps screen-reader users understand the content and may appear when the image file is unavailable. The editor’s task is therefore to preserve the information or purpose of the element when the image cannot be seen. Requiring a keyword in every field does not achieve this.

Search engines also use descriptions. However, a missing alt attribute does not prove that an image is excluded from search, and filling it in does not guarantee impressions or enquiries. For example, Yandex explains the role of alt text as additional information for its image crawler. Do not replace accessibility checks with a promise of SEO gains.

Start with one real scenario: a shopper choosing a product colour, a reader studying a diagram or a visitor pressing a button. Write down what they need to learn or do. This is a better basis for judging alt text than character count. Below, we use a fictional desk-lamp catalogue; the model names and example data are invented.

Distinguish alt text, captions, filenames and structured data

The media library places several fields next to one another. They may look interchangeable, but serve different purposes on the published page. Before filling them in at scale, establish where your template displays each value.

The title “N-7 lamp” in the file library does not prove that it has become the image’s alternative text. Conversely, correct alt text does not fix an unrelated cover image in an article card. These are two separate checks.

Do not rename files already in use just to get a tidier address without checking links. A new URL requires updating every insertion point and checking that older pages still load their resources. For new uploads, choose a clear filename in advance.

Identify the role of each image

Open the W3C WAI decision tree. First establish whether the image conveys information, triggers an action or is decorative. Knowing that it is a photograph is not enough: the same photo can be a product image, a banner background or a category link.

1. Does it carry useful information? Specify which part of the content the text needs to replace.
2. Is it a link or button? Check whether its purpose is clear without the image and whether the same element already contains text.
3. Is it a complex diagram? Plan an explanation or data alongside the short alt text.
4. Is the meaning already conveyed, with the image only decorating the section? Consider an empty alt="".

Add a “Why this option was chosen” column to your working table. A note such as “decorative icon; the benefit is named beside it” helps the next editor preserve the decision. Without it, the next automated audit may turn decoration back into unnecessary spoken words.

Do not classify all visual styling as decorative in advance. If the only difference between two product variants is visible in the photo, that image conveys information even when the model name is already printed beside it.

Write what someone needs to understand without the image

For an ordinary informative photo, start with the subject, then add a useful distinguishing detail. In our catalogue, this might be the model, body colour or detail shown. Check every word against the image and reliable product information.

“N-7 desk lamp, graphite body, articulated arm” describes the visible object. “Buy the best cheap lamp with delivery” describes the seller’s wish. Do not add materials, awards, compatibility or specifications to alt text unless you can verify them.

A useful editing technique is to write a full explanation first, then remove anything that does not help the current task. Colour matters when choosing a variant, but may not matter in an instruction about the switch location. Words such as “photo” or “diagram” are useful when the format itself matters; there is no need to ban them mechanically.

Do not impose a universal requirement of 100, 125 or 150 characters. The task determines the length. Put a long technical explanation in the main text and keep the short alternative as a reference point. In W3C technique H37 the main criterion is to convey the image’s meaning; important words within the image must not be lost either.

Review a gallery, banner and instructional screenshot

These examples cover different places on a site. Do not apply them automatically to your photos: first compare each wording with the actual image and the surrounding text.

Do not chase artificial uniqueness by changing “side view” to “view from the side” for identical shots. If the images convey the same information, repeating the text is not an error in itself. If the shots differ, the text should communicate the useful difference.

Check the gallery’s main image and thumbnail buttons separately. A thumbnail may switch the displayed image, so users need a clear action name such as “Show brightness control”, not just a description of the pixels.

Do not confuse a missing attribute with an intentionally empty value

WAI guidance on decorative images allows an empty alt attribute to prevent decoration being read as content. But omitting the attribute is different: some screen readers may then announce the filename.

<!-- Informative photo -->
<img src="lamp-n7.webp"
     alt="N-7 desk lamp in graphite">

<!-- Decoration that adds no information -->
<img src="section-divider.webp" alt="">

<!-- Image is the only link content -->
<a href="/catalog/lamps/">
  <img src="lamps-category.webp" alt="Desk-lamp catalogue">
</a>

<!-- Purpose is already stated by text in the same link -->
<a href="/instructions/lamp-n7.pdf">
  <img src="pdf-icon.svg" alt="">
  Download the N-7 lamp manual (PDF)
</a>

In the WAI guide to functional images the emphasis is on the purpose of the action. Check the entire link or button, not the image field in isolation: an additional name supplied through ARIA may also affect the result.

A practical test: read the element’s name without looking at its picture. If it says only “icon”, “image” or a filename, the action is hard to understand. If the same phrase is repeated twice, check whether you have redundantly described a decorative icon.

Give complex images a text explanation

A chart, map or process diagram may carry more information than a useful short alternative can hold. Under WAI guidance for complex images, supplement the short description with an accessible detailed explanation. The format depends on the content: a data table, a sequence of steps or a description of relationships.

An example chart shows 12, 18 and 15 enquiries across three months. The alt text “Enquiries from January to March; values are in the table below” points readers to an equivalent. Beside it, you could write: “After rising in the second month, enquiries fell but remained above the first month.” If that conclusion matters to the article, provide it in ordinary text, not only as a line on the chart.

A CRM configuration diagram needs the order of actions and the conditions for moving between steps. A floor plan needs the object’s location and the route to it. Do not settle for “details in the image”: that sends the reader back to the same inaccessible source.

Check alt text on the published page

Open the page as an ordinary visitor. Find the image, open its context menu and choose the command to inspect the element. The command’s name depends on the browser; in Chrome, it opens the developer tools’ Elements panel. Locate the actual img, not an enclosing link or container.

1. Check whether the attribute alt exists and what its value is.
2. Compare the value with the image and surrounding text.
3. If it is a button or link, inspect the name of the entire interactive element in the browser’s accessibility panel.
4. Repeat after opening the gallery, switching a product variant and using a narrow screen.

For developers, this short browser-console check lists all img elements in the current document. It only reads the page and prints a table; it sends and changes nothing.

console.table(Array.from(document.images, (img, index) => ({
  number: index + 1,
  source: img.currentSrc || img.src,
  state: !img.hasAttribute('alt') ? 'attribute missing'
    : img.alt.trim() ? 'has text' : 'empty value',
  alt: img.getAttribute('alt')
})));

This list does not assess wording quality, CSS backgrounds, images in other documents or every possible application state. It also reflects the current DOM after scripts have run. If the source HTML and the loaded page have different values, identify which component replaces the image.

Collect images and source pages in Screaming Frog

One file can appear in dozens of places with different purposes. To fix it, you therefore need both the file list and the addresses of the pages where it is used.

1. Install Screaming Frog SEO Spider from the official website. Enter the starting URL in Enter URL to spider and start the crawl with Start.
2. Open the Images tab. Review these filters separately: Missing Alt Attribute and Missing Alt Text.
3. Select an image and open the lower Image Details tab to connect the file to its usage locations.
4. Use Bulk Export → Images → All Images to export all images with their source pages and alt text. Available menu items may differ in your version.
5. Flag informative images without alternatives, decorative exceptions, inaccurate descriptions and unclear link names.

The filter names and export process are documented in the official Screaming Frog guide. The Missing Alt Text filter includes empty values: do not treat every row as an error without reviewing it.

Record the scope: sections crawled, URLs excluded, software limits and restricted pages. If an expected gallery is absent from the export, check its JavaScript loading and crawl settings. “No errors found” says nothing about pages the check never saw.

Fix the specific image instance

For a standard image block, open the relevant post or page, select the image and find the alternative-text setting. Fill it in according to the image’s role, or mark it as decorative if your version offers that option. Save the page and reopen its public URL.

WordPress documentation distinguishes the block’s local setting from the media-library value: the block text applies to one specific location, while the library provides the initial value when inserting an image. Do not assume that changing the library automatically rewrites every older insertion.

If the image is in a Media & Text block, check that block’s own settings. A page builder, product gallery or theme template may obtain alt text elsewhere. For an HTML insertion, change the attribute of the img element itself; for a shared component, change the rule that generates its markup.

This report identifies the location and the observed result. “Add alt everywhere” does not explain which template is broken or which exceptions must be preserved.

Fix the recurring rule, then check the exceptions

For a large catalogue, agree on the source fields: model name, colour, angle and detail. Build the rule only on reliably populated data. If the viewing angle is not stored, do not invent it at random. A short accurate text is better than a detailed fiction.

Apply the rule to a small test sample first. Include a standard product, several colours, incomplete specifications, a sold-out variant, a gallery and a product without a photo. Check for the literal word “undefined”, an internal SKU replacing the name, or a description of the wrong colour variant.

Keep the text tied to where the image is inserted. A lamp file on the homepage may illustrate a category, while in a product gallery it may show a specific configuration. One shared media-library field may not suit both tasks. On multilingual sites, alternative text must match the surrounding content’s language.

AI can suggest a draft, but an editor must verify the subject, context and purpose. Be especially cautious with recognised lettering, chart numbers and technical details. Before a bulk update, export the old values, agree on exceptions and establish a rollback procedure. Template changes can be included in technical website development.

Separate file problems from alt-text quality

If an image fails to load, open its URL and check the server response. Access errors, deleted files and crawling restrictions need separate fixes. Useful guides: finding broken links and checking robots.txt.

Google recommends standard image elements with a working src attribute, helpful context and appropriate alternative text. Google does not index CSS backgrounds as ordinary page images. For a responsive picture element, set alt on its nested img element; file variants must preserve the meaning. An alt attribute cannot compensate for a mobile crop that removes an essential detail.

Dimensions, compression and lazy loading affect speed; they do not replace a text alternative. Check them in PageSpeed Insights. Then manually confirm that the image appears when scrolling, does not overlap its caption and remains readable on a phone.

Do not promise a fixed traffic increase after filling in alt text. Record the change date and affected pages, then monitor image impressions and clicks in the available search-console reports. Account for seasonality, catalogue changes and other improvements. Business outcomes depend on the visitor’s whole journey, so image checks are useful alongside SEO for your pages.

Close the task with verification, not just an export without red rows

After publication, repeat the crawl using the same method. Compare the same sections and save a dated report. The exceptions list should explain remaining empty alt attributes, not conceal unchecked images. Tick items only for verified results; this checklist does not send data.

In the final report, include several verifiable before-and-after examples, page URLs, the template owner and remaining limitations. For a full site launch, include these results in website acceptance testing.

Frequently asked questions about image alt text