SEOLZ

Role img alt

Quick win

Found on 2% of audited stores.

Add an accessible text label (aria-label) to every element that has role="img" so screen readers can announce what the image conveys.

What it is

When a non-image HTML element (like a `<div>`, `<span>`, or SVG) is given `role="img"` to indicate it acts as an image, browsers and screen readers still need a text description to announce to blind or low-vision users. That description is supplied via an `aria-label` attribute (or an `aria-labelledby` pointing to visible text). If that label is missing or empty, screen readers either skip the element silently or announce something useless like "image" — leaving visitors with no idea what it represents. WCAG Success Criterion 1.1.1 (Non-text Content) requires that every image-like element has a meaningful text alternative.

Why it matters

Roughly 7–8 million Americans use screen readers, and accessibility lawsuits against ecommerce stores have risen sharply every year — missing image labels are one of the most frequently cited violations in ADA Title III litigation. Beyond legal risk, Google's crawler also processes ARIA labels and treats them as descriptive signals, so properly labeled decorative graphics and icon-based UI elements contribute to a cleaner, more crawlable page. Most importantly, customers who rely on assistive technology simply cannot use your store if they cannot understand what your images, icon buttons, SVG badges, or star-rating widgets are — leading to lost sales and brand damage.

How to fix it

  1. Identify every element in your HTML that has role="img" — these are commonly SVGs, icon fonts wrapped in a <span> or <div>, CSS-based image containers, or custom widgets like star ratings.
  2. Decide whether the element is meaningful (conveys information) or purely decorative. If decorative, either remove role="img" entirely or add aria-hidden="true" so screen readers skip it.
  3. For meaningful elements, add a concise, descriptive aria-label attribute directly on the element — e.g., aria-label="4 out of 5 stars" or aria-label="Free shipping badge".
  4. Alternatively, if descriptive text already exists visibly on the page nearby, use aria-labelledby="id-of-that-text" to reference it instead of duplicating the label.
  5. Check SVG elements specifically: an inline SVG used as an image should have role="img" AND either an aria-label on the <svg> tag or a <title> element as its first child (which also satisfies the requirement).
  6. Validate the fix using a browser accessibility checker (e.g., axe DevTools browser extension) or a screen reader (NVDA, VoiceOver) to confirm the element is now announced with meaningful text.
<svg role="img" aria-label="4 out of 5 stars customer rating" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 20">
  <!-- star path data -->
</svg>

<!-- Decorative icon — hidden from screen readers -->
<span role="img" aria-hidden="true" class="icon-truck"></span>

<!-- Label references visible text elsewhere on the page -->
<div role="img" aria-labelledby="badge-label" class="free-shipping-badge"></div>
<p id="badge-label">Free Shipping on orders over $50</p>

Fix it on your platform

Pick your platform for the exact steps.

How to fix role img alt on Shopify
  1. Go to Online Store → Themes → click the three-dot menu next to your active theme → Edit code.
  2. In the Layout or Sections panel, open the template file where the flagged element lives (e.g., sections/product-template.liquid, snippets/icon-star.liquid, or snippets/icon.liquid for SVG icons).
  3. Locate the element with role="img" — often an SVG or a <span> wrapping an icon font.
  4. Add aria-label="[descriptive text]" directly to the opening tag, e.g., <svg role="img" aria-label="Free shipping badge" ...>. For icon snippets that are purely decorative, add aria-hidden="true" instead.
  5. For Shopify's built-in star-rating or review app snippets, search snippets/ for 'role="img"' and patch each occurrence.
  6. Save the file, then preview the live theme and verify with axe DevTools or a screen reader.
Full Shopify guide →Official Shopify docs ↗
How to fix role img alt on WooCommerce
  1. Access your WordPress dashboard → Appearance → Theme File Editor (or use a child theme / FTP for safer editing).
  2. Search your active theme's template files (e.g., woocommerce/single-product.php, template-parts/, or a page-builder shortcode output) for role="img".
  3. Add aria-label="[descriptive text]" to each flagged element, or aria-hidden="true" for decorative ones.
  4. If the element is generated by a plugin (e.g., a reviews plugin rendering star SVGs), check the plugin's settings for a built-in accessibility label field, or use a Code Snippets plugin to enqueue a small JavaScript fix: document.querySelectorAll('[role="img"]').forEach(el => { if (!el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby')) el.setAttribute('aria-label', 'Rating graphic'); });
  5. Alternatively, install the 'WP Accessibility' plugin which patches several common ARIA label issues automatically.
  6. Test with the axe browser extension after saving.
Full WooCommerce guide →Official WooCommerce docs ↗
How to fix role img alt on BigCommerce
  1. Go to Storefront → My Themes → click Customize on your active theme → click Advanced → Edit Theme Files (or use the Stencil CLI locally).
  2. Search theme template files (templates/components/, templates/pages/) for role="img" using your editor's Find in Files feature.
  3. Open the relevant .html Handlebars template and add aria-label="[descriptive text]" to each flagged element.
  4. For SVG icons in the cornerstone theme, check templates/components/icons/ — each SVG partial should have role="img" and aria-label, or aria-hidden="true" if decorative.
  5. Commit and push changes via Stencil CLI (stencil push) or save directly in the theme editor, then publish.
  6. Verify with axe DevTools on your live storefront.
Full BigCommerce guide →Official BigCommerce docs ↗
How to fix role img alt on Adobe Commerce (Magento)
  1. Locate the relevant PHTML template or layout XML in your custom theme under app/design/frontend/<Vendor>/<Theme>/.
  2. Search across templates for role="img" using grep -r 'role="img"' app/design/ in the CLI.
  3. In each flagged template, add aria-label="<?= $block->escapeHtmlAttr(__('Descriptive text')) ?>" to the element, using Magento's translation/escaping helpers.
  4. For SVGs included via the Magento SVG icon system, edit the relevant .phtml partial in Magento_Theme or your override and add the aria-label there.
  5. Run bin/magento cache:flush after saving, then test on the storefront with axe DevTools.
Full Adobe Commerce (Magento) guide →Official Adobe Commerce (Magento) docs ↗
How to fix role img alt on Wix
  1. Open the Wix Editor for your site.
  2. Click the element flagged (e.g., a vector image, icon, or decorative shape). In the panel that appears, look for Accessibility Settings or the Settings → Accessibility tab (available on image and vector elements).
  3. In the 'Alt Text' or 'ARIA Label' field, type a concise description of what the element represents.
  4. For Wix Studio, use the Accessibility panel in the Inspector on the right sidebar to add an ARIA label to any element with role="img".
  5. If the element is a Wix App widget (e.g., Wix Stores product badge), check the app's settings for an accessibility or alt-text field.
  6. Publish the site and verify using axe DevTools in your browser.
Full Wix guide →Official Wix docs ↗
How to fix role img alt on Squarespace
  1. In your Squarespace editor, click the image or icon block that contains the element.
  2. For standard Image Blocks, open block settings and fill in the Alt Text field — Squarespace maps this to the accessible label.
  3. For custom SVG or icon elements injected via a Code Block (Settings → Advanced → Code Injection or a Code Block on the page), edit the HTML directly and add aria-label="[descriptive text]" to the element with role="img".
  4. For purely decorative icons in code blocks, add aria-hidden="true" instead.
  5. Save and preview the page, then run axe DevTools to confirm the label is present.
Full Squarespace guide →Official Squarespace docs ↗
How to fix role img alt on Webflow
  1. Open your project in the Webflow Designer and select the element flagged (e.g., an SVG embed, Lottie animation div, or icon element).
  2. In the right-hand panel, open the Element Settings tab (the gear icon).
  3. Scroll to the Accessibility section and enter your label in the 'Custom attributes' area: add attribute name aria-label with the descriptive value, e.g., '4 out of 5 stars'.
  4. For purely decorative elements, add aria-hidden with value true instead.
  5. For SVG elements embedded via an Embed component, click the embed, open the code, and manually add aria-label="[text]" to the <svg> tag.
  6. Publish the site and validate with axe DevTools.
Full Webflow guide →Official Webflow docs ↗

Does your site have this issue?

Run a free SEOLZ audit to find role img alt — and every other issue — across your whole site in minutes.

Scan my site free

Frequently asked questions

What is Role img alt?

When a non-image HTML element (like a `<div>`, `<span>`, or SVG) is given `role="img"` to indicate it acts as an image, browsers and screen readers still need a text description to announce to blind or low-vision users. That description is supplied via an `aria-label` attribute (or an `aria-labelledby` pointing to visible text). If that label is missing or empty, screen readers either skip the element silently or announce something useless like "image" — leaving visitors with no idea what it represents. WCAG Success Criterion 1.1.1 (Non-text Content) requires that every image-like element has a meaningful text alternative.

Why does role img alt matter?

Roughly 7–8 million Americans use screen readers, and accessibility lawsuits against ecommerce stores have risen sharply every year — missing image labels are one of the most frequently cited violations in ADA Title III litigation. Beyond legal risk, Google's crawler also processes ARIA labels and treats them as descriptive signals, so properly labeled decorative graphics and icon-based UI elements contribute to a cleaner, more crawlable page. Most importantly, customers who rely on assistive technology simply cannot use your store if they cannot understand what your images, icon buttons, SVG badges, or star-rating widgets are — leading to lost sales and brand damage.

How do I fix role img alt?

Add an accessible text label (aria-label) to every element that has role="img" so screen readers can announce what the image conveys.

Authoritative references

Related Accessibility (WCAG) issues