Writing Alt Text Correctly: More Than Just a Required Field

1. Why most alt text is useless despite being present

In most Magento catalogs, the alt attribute is technically filled in. The product import automatically sets the product name as alt text, an editor ticks the required field in the backend, an audit tool reports a green light at one hundred percent coverage. Yet screen reader users clicking through a category page hear nothing but an endless repetition of the same product name, without ever learning which color, which material, or which angle the particular image actually shows. The mere presence of an alt text says nothing about its usefulness.

The fundamental misunderstanding: an alt text is not an SEO keyword field or a box to tick for a WCAG compliance checklist, it is a functional text alternative. It must convey the same information or function that a sighted user takes away from the image. For a product photo that is usually the visual description of the item, for an infographic it is the core message contained in it, for an icon button it is the function of the button. Anyone who fails to distinguish these three cases produces alt text that technically satisfies WCAG criterion 1.1.1 while still failing the screen reader user.

The following sections show concretely how alt text needs to differ depending on the image type, when an empty alt="" is the correct and only right choice, and how to audit an existing product catalog not just for presence but for genuine content quality.

2. The ground rules for a good alt text

A good alt text is always context-dependent. The same product photo needs a different alt text on the category page than on the product detail page or in a cart preview, because the surrounding context already provides information that does not need to be repeated in the image description. On a category page with the visible product name right next to it, a short visual addition is often enough. On a product detail page with several images in a gallery, the alt text must name the specific angle or detail view so the images can even be told apart.

The second ground rule is conciseness. Screen readers read out the complete alt text before moving to the next focus point. An alt text with three nested clauses noticeably slows down navigation. A rough guideline is 125 characters, because some older screen reader versions truncate longer texts anyway, but more important than character count is information density: every word must carry information, no filler, no repetition of context that is already obvious from the surroundings.

The third and most frequently violated rule: an alt text never starts with phrasing like image of, photo of, or graphic showing. Screen readers already announce an image as such before reading out the alt text. The phrase image of red hiking boot size 42 is therefore heard as image, image of red hiking boot size 42, redundant and disruptive. The correct phrasing describes the content directly: red hiking boot with lug sole, side view.

<!-- WRONG: redundant announcement, screen readers already say "image" -->
<img src="hiking-boot-red.jpg" alt="Image of red hiking boot size 42">

<!-- WRONG: filename dumped into alt, no actual description -->
<img src="IMG_20260304_hiking_boot_red_042.jpg" alt="IMG_20260304_hiking_boot_red_042">

<!-- WRONG: alt attribute completely missing -->
<img src="hiking-boot-red.jpg">

<!-- RIGHT: concise, context-independent, describes what is actually visible -->
<img src="hiking-boot-red.jpg" alt="Red hiking boot with lug sole, side view">

3. Writing alt text for product photos

Product photos are the most common image type in a Magento catalog, and at the same time the area with the greatest automation potential and the greatest risk of generic, mass-produced text. The product name alone almost never works as alt text, because it usually already appears as visible text next to the image, and screen reader users end up hearing that information twice without gaining any value from the image itself. A good product photo alt text supplements the product name with what is actually only visible in the image: color, material, angle, context of use, visible details like seams, fastenings, or patterns.

For image galleries with several views of the same product, every alt text must clearly name the respective angle, otherwise a screen reader user cannot meaningfully browse the gallery. Instead of the same generic text five times over, five distinguishable descriptions are needed: front view, side view, detail view of the sole, top view, close-up of the fastening. For configurable products with color options, the alt text should name the variant that is actually displayed, not the product's default variant, since the image changes via JavaScript when the variant is switched without a full page reload.

<!-- Hyvä phtml: gallery images with distinguishable, context-aware alt text -->
<?php foreach ($block->getGalleryImages() as $image): ?>
    <img
        src="<?= $block->escapeUrl($image->getUrl()) ?>"
        alt="<?= $block->escapeHtmlAttr($image->getAccessibleAltText()) ?>"
        loading="lazy"
        class="w-full h-auto object-cover rounded-lg"
    >
<?php endforeach; ?>

<!-- ViewModel: alt text combines product attribute + view angle, not just name -->
<?php
// getAccessibleAltText() returns e.g. "Red hiking boot, sole tread detail"
// instead of just repeating "Hiking Boot Model X" for every single image
?>

4. Alt text for infographics and complex images

Infographics, size charts rendered as images, diagrams, and comparison graphics carry structured information that a single-line alt text can never fully capture. The most common mistake is trying to squeeze an entire size chart into a 125-character alt text, which inevitably results in incomplete or unusable information. The correct solution uses alt only for a short summary of the image's purpose and provides the complete information additionally as readable text or as a real HTML table directly next to or below the image.

For more complex cases, the aria-describedby attribute is useful, pointing to a longer description elsewhere in the document while alt still contains the short summary. It is important that this longer description does not necessarily have to be visible to sighted users, but it must never be hidden with display: none, since some screen reader combinations then ignore such elements too. The CSS class sr-only, which visually hides content while keeping it accessible in the accessibility tree, is the established pattern here.

<!-- Infographic with short alt + full data available as real accessible text -->
<figure>
    <img
        src="/media/size-chart-shoes.png"
        alt="Shoe size chart: EU sizes 36 to 46 with foot length in centimeters"
        aria-describedby="size-chart-details"
    >
    <div id="size-chart-details" class="sr-only">
        EU 36 corresponds to 22.5 cm foot length. EU 38 corresponds to 24 cm.
        EU 40 corresponds to 25.5 cm. EU 42 corresponds to 27 cm. EU 44 corresponds to 28.5 cm.
    </div>
</figure>

<!-- Better long-term: skip the image entirely, use a real HTML table -->
<table>
    <caption>Shoe size chart</caption>
    <thead><tr><th scope="col">EU size</th><th scope="col">Foot length</th></tr></thead>
    <tbody>
        <tr><td>36</td><td>22.5 cm</td></tr>
        <tr><td>38</td><td>24 cm</td></tr>
    </tbody>
</table>

5. Marking up icons, buttons, and decorative images correctly

Icons occur in two fundamentally different roles that each require different treatment. An icon that is purely decorative next to an already existing text label, for example a small cart symbol right next to the visible words Add to Cart, needs no separate alt text of its own, because the function is already fully communicated through the text. A duplicate alt text with the same content would only unnecessarily lengthen the output and slow down the interaction.

It is different for an icon button without visible text, for example a plain magnifier symbol for search or an X symbol to close a modal. Here the icon carries the entire functional information and must therefore be labeled either via aria-label on the button element or via a visually hidden sr-only text. What matters is naming the function, not the visual appearance: aria-label="Open search" is correct, aria-label="Magnifier icon" only describes the shape and does not help the user understand the action. For SVG icons, aria-hidden="true" is additionally applied to the SVG element itself when the label already sits on the enclosing button, so the screen reader does not announce the icon twice.

Purely decorative background or spacer images such as ornamental dividers always get an empty alt="" together with role="presentation", since they carry no information a screen reader user needs.

6. When alt="" is actually the right choice

An empty alt="" is a legitimate pattern explicitly foreseen by WCAG, not a sign of carelessness. It actively signals to screen readers that an image is purely decorative and should be skipped entirely when reading out the page. This is fundamentally different from a missing alt attribute: if alt is missing entirely, screen readers often fall back to the filename or still announce the image as an unknown graphic element, which is more confusing for users than a deliberately empty attribute.

Typical candidates for alt="" are purely decorative dividers, background patterns, corner ornaments, border elements, and images whose information is already fully present in the surrounding text, for example a small checkmark icon right next to the text In Stock, which already textually describes availability. The rule of thumb: if removing the image would cause no loss of information whatsoever for a user who cannot see the page, alt="" is correct. If the image conversely conveys information that appears nowhere else in the text, it needs a descriptive alt text.

A common mistake with rating stars in Magento product listings: five individual star icons each with alt="Star" produce a pointless string of five identical announcements. The correct approach is either an empty alt="" on each individual star icon combined with an aria-label="4.5 out of 5 stars, 128 reviews" on the enclosing container, or a purely textual sr-only addition at the same location.

7. Delivering alt text correctly in Magento and Hyvä

In Magento, the alt attribute for product images is generated by default from the Label field of the media gallery entries, or, if that stays empty, from the product name. That exact fallback is the main cause of generic, unhelpful alt text in the catalog: editors upload product images without filling in the label field, and every image of a product automatically receives the same alt text. A ViewModel that prepares the media gallery data should therefore check whether a curated label exists, and only fall back to the product name in the genuine fallback case, combined with the position within the image array.

In Hyvä templates it is worth having a central helper or ViewModel that consistently applies escapeHtmlAttr() to every alt text to prevent HTML injection via curated editorial data, while also enforcing a length limit so that accidentally pasted body copy does not end up as an 800-character alt text on the frontend. For imported product data from PIM systems or supplier feeds, a validation rule in the import process is recommended that automatically flags empty or filename-looking alt text instead of silently accepting it.

{
  "media_gallery_entry": {
    "id": 4821,
    "label": "Red hiking boot, sole tread detail",
    "position": 3,
    "types": ["image", "small_image"],
    "file": "/h/i/hiking-boot-red-sole.jpg"
  },
  "fallback_rule": "If label is empty: '{product_name}, view {position}' instead of a plain repeated product name",
  "validation": {
    "min_length": 10,
    "max_length": 150,
    "reject_if_equals_filename": true,
    "reject_if_starts_with": ["Image of", "Photo of", "Graphic showing", "IMG_", "DSC_"]
  }
}

8. Auditing an existing catalog for genuine alt text quality

A pure completeness check that only reports whether the alt attribute contains any value at all almost entirely misses the actual quality problems. An automated audit script should therefore combine several heuristics: is the alt text identical to the filename? Does it start with one of the known filler phrases like image of or photo of? Is it shorter than ten characters and thus probably too generic? Is it longer than 250 characters and thus probably a copied block of body text rather than an actual description? Does the exact same alt text repeat across more than three different products, suggesting a mass-copied template?

Such a script can be run as a CLI command against the Magento database and delivers a prioritized list instead of a plain yes-no coverage rate. What matters in practice: automated heuristics reliably detect technical symptoms of poor alt text but cannot judge content accuracy, for example whether a color description actually matches the image. An automated audit is therefore the first filtering stage that delivers candidates for a manual editorial sample, not a replacement for human review on the most frequently visited product pages.

// Node.js audit script: flag catalog images with low-quality alt text
const fillerPhrases = ['image of', 'photo of', 'graphic showing', 'picture of'];
const filenamePattern = /^(img|dsc|photo)[_-]?\d+/i;

function auditAltText(altText, filename) {
  const issues = [];
  const normalized = (altText || '').trim().toLowerCase();

  if (!normalized) issues.push('EMPTY_OR_MISSING');
  if (normalized === filename.toLowerCase()) issues.push('EQUALS_FILENAME');
  if (filenamePattern.test(normalized)) issues.push('LOOKS_LIKE_FILENAME');
  if (fillerPhrases.some(p => normalized.startsWith(p))) issues.push('FILLER_PREFIX');
  if (normalized.length > 0 && normalized.length < 10) issues.push('TOO_SHORT');
  if (normalized.length > 250) issues.push('TOO_LONG_LIKELY_COPY_PASTE');

  return { altText, filename, issues, needsReview: issues.length > 0 };
}

// Usage against exported product image data
const results = productImages.map(img => auditAltText(img.alt, img.filename));
const flagged = results.filter(r => r.needsReview);
console.log(`${flagged.length} of ${results.length} images flagged for manual review`);

9. Alt text head to head: bad vs. good

The following overview summarizes the most common image types in a Magento catalog and contrasts a typical bad pattern with a concretely improved alt text for each.

The common denominator of all five examples: a good alt text does not come from a longer string of characters, but from the deliberate decision about which information would actually be missing at that point for a screen reader user. That decision can be partially automated and audited, but for product images with many variants and angles it still requires editorial care when creating the media gallery entries.

10. Summary

A good alt text is not a required field filled in with the product name, it is a functional text alternative that follows the image type and its surrounding context. Product photos need details that are only visible in the image and meaningfully supplement the product name instead of repeating it. Infographics and size charts additionally need to be provided as real text or a real HTML table, because a single-line alt text cannot carry complex information. Icon buttons without visible text need a function-describing aria-label, while purely decorative images should get a deliberately empty alt="".

The biggest lever for existing Magento catalogs rarely lies in a one-off correction, but in structural safeguards: a ViewModel that implements fallback logic cleanly, an import validation that automatically flags generic patterns, and a recurring audit script that catches new quality problems before they multiply across thousands of products. Automated heuristics do not replace editorial review, but they provide the prioritization needed to focus that review on the most relevant cases.

11. FAQ: Writing Alt Text Correctly