Role img alt
Moderate effortFound on 5% of audited stores.
Add a meaningful aria-label (or aria-labelledby) to every element with role="img" so screen readers can announce what the image represents.
What it is
When a developer uses the HTML attribute `role="img"` on an element that isn't a native `<img>` tag — for example, an icon font character, an SVG group, a `<div>` containing a decorative graphic, or an emoji used as meaningful content — they are telling browsers and assistive technologies "treat this as an image." However, unlike a real `<img>` tag which has an `alt` attribute, these elements have no built-in place to put a text description. The `aria-label` attribute fills that gap: it provides the invisible text label that a screen reader will read aloud instead of the visual graphic. If `aria-label` (or an equivalent like `aria-labelledby`) is missing or empty, the element is announced to blind or low-vision users as an unlabelled image — or skipped entirely — making it meaningless.
Why it matters
WCAG 2.1 Success Criterion 1.1.1 (Level A — the most basic accessibility level) requires that all non-text content has a text alternative. Failing this criterion means your store is inaccessible to the roughly 7–8 million people in the US alone who use screen readers, exposing you to legal risk under the ADA, Section 508, and equivalent laws in the EU (EAA 2025), UK, Australia, and Canada — accessibility lawsuits against ecommerce stores have increased sharply year-over-year. Beyond legal risk, unlabelled icons and graphics mean blind shoppers cannot understand product badges, trust seals, star ratings rendered as icon fonts, or navigation icons — directly harming conversions and checkout completion rates. Google also uses accessibility signals as part of its overall quality assessment, so a deeply inaccessible site can experience reduced crawl quality over time.
How to fix it
- Identify every element in your theme or page builder output that has the attribute role="img" — search your HTML source, theme files, and any custom code blocks for this string.
- For each element, decide whether it is meaningful (conveys information a sighted user would understand, e.g. a star-rating icon, a trust badge, a logo rendered as an SVG) or purely decorative (adds no information). Decorative images should instead use role="presentation" or aria-hidden="true" to hide them from screen readers entirely.
- For meaningful elements: add aria-label="[concise description]" directly on the element with role="img", e.g. aria-label="4.5 out of 5 stars". The description should convey the same information a sighted user gets from the graphic.
- Alternatively, if a visible text caption already exists nearby, use aria-labelledby="[id-of-caption-element]" instead of duplicating text in aria-label.
- For SVG elements specifically: add a <title> element as the first child of the <svg>, give it a unique id, then set aria-labelledby="[title-id]" on the <svg> element — this is the most robust pattern across screen readers.
- Validate the fix using a browser accessibility tree inspector (Chrome DevTools → Accessibility tab) or re-run your axe scan to confirm the rule "role-img-alt" no longer fires.
Fix it on your platform
Pick your platform for the exact steps.
How to fix role img alt on Shopify
- In Shopify Admin, go to Online Store → Themes → click 'Customize' on your active theme.
- For SVG icons or icon-font spans in your theme code: click 'Edit code' (three-dot menu next to the theme name) to open the theme code editor.
- Search for 'role="img"' across all Liquid files (use the search box at the top of the file tree).
- On each matching element, add aria-label="[description]" as an attribute, e.g. <span role="img" aria-label="Free shipping"> or on an SVG: add a <title id="icon-title">Free shipping</title> as the first child and set aria-labelledby="icon-title" on the <svg role="img"> element.
- For third-party sections or apps that inject HTML you cannot edit, contact the app developer or use a theme.liquid script injection to patch the rendered DOM after page load as a last resort.
- Save and preview with a screen reader (VoiceOver on Mac, NVDA on Windows) or re-run an axe browser extension audit to verify.
How to fix role img alt on Shopify Plus
- Same as Shopify: Online Store → Themes → Edit code.
- In Shopify Plus you may also have a checkout.liquid file — search it for role="img" and apply the same aria-label fix there.
- Use the Shopify CLI locally for bulk search: run 'grep -r "role=\"img\"" ./templates ./sections ./snippets' to find all occurrences at once, then edit and push.
How to fix role img alt on WooCommerce
- In WordPress Admin, go to Appearance → Theme File Editor (or use a local IDE with your child theme files).
- Search your active child theme files for role="img" — common locations: header.php, functions.php, template-parts/, and any custom plugin shortcodes.
- Add aria-label="[description]" to each flagged element in the template file.
- For SVG icons added via a plugin (e.g. WooCommerce product badges), check the plugin's settings for an 'Alt text' or 'Label' field; if none exists, use a custom CSS/JS snippet via Appearance → Customize → Additional CSS / Additional JS, or a plugin like 'Code Snippets' to patch the output.
- If icons come from an icon font plugin (e.g. Font Awesome), wrap each meaningful icon in a <span role="img" aria-label="[description]"> and add aria-hidden="true" to the inner icon element.
- Run the axe DevTools browser extension on your storefront to confirm the issue is resolved.
How to fix role img alt on BigCommerce
- In BigCommerce Admin, go to Storefront → My Themes → click 'Advanced' → 'Edit Theme Files' on your active theme.
- Use the file search to find role="img" across your Stencil theme's .html and .handlebars template files.
- Add aria-label="[description]" to each element, following the same pattern as the generic HTML steps.
- For SVG sprites (common in Stencil), locate the SVG sprite file (often templates/layout/base.html or assets/img/ SVG files), add <title id="unique-id">[Description]</title> as the first child of each <symbol>, and reference it with aria-labelledby on the <svg role="img"> usage site.
- Push changes and validate with a screen reader or the axe browser extension.
How to fix role img alt on Wix
- In the Wix Editor, click on the element (icon, vector art, or decorative section) that has been flagged.
- In the right-hand panel, look for 'Accessibility' settings — Wix exposes a 'What does this element do?' or 'ARIA label' field for many element types.
- Type a meaningful description in the ARIA label field (e.g. 'Customer review: 5 stars').
- For Wix Studio or custom-coded Velo components, open the Page Code panel and add the aria-label attribute programmatically: $w('#elementId').setAttribute('aria-label', 'Your description here');
- For icon elements that are purely decorative, use the Accessibility panel to set them as 'Decorative' (role presentation / aria-hidden).
- Publish and re-test with the axe browser extension.
How to fix role img alt on Wix Studio
- In Wix Studio, select the flagged element on the canvas.
- Open the Settings panel on the right → scroll to the 'Accessibility' section.
- Enter a descriptive label in the 'ARIA Label' field.
- For custom components or HTML embeds, edit the embed code directly and add aria-label="[description]" to the role="img" element.
- Use the Velo IDE (Dev Mode) for programmatic access: $w('#myIcon').setAttribute('aria-label', 'Description');
- Publish and validate with axe DevTools.
How to fix role img alt on Squarespace
- In Squarespace, go to Pages → select the page → click Edit.
- For an Icon Block, click the icon to open its settings; look for an 'Alt Text' or 'Accessible Label' field and fill it in.
- For SVG or Code Blocks containing role="img" HTML, click the block → Edit → and update the HTML directly to include aria-label="[description]" on the role="img" element.
- For template-level icon fonts (e.g. social icons in the footer), go to Design → Custom CSS and inject a JavaScript fix via Settings → Advanced → Code Injection (header or footer): add a <script> that finds each [role='img'] without aria-label and adds one.
- Squarespace does not expose direct theme file editing, so Code Injection is the primary route for template-controlled elements.
- Validate with the axe browser extension after saving.
How to fix role img alt on Webflow
- In the Webflow Designer, select the element flagged (often an Icon element or an Embed with an SVG).
- Open the Element Settings panel (D key) → scroll to 'Custom Attributes'.
- Add a new attribute: Name = aria-label, Value = [your description, e.g. 'Verified purchase badge'].
- If the element is decorative, add aria-hidden with value true instead.
- For SVG embeds added via an HTML Embed component, edit the embed code and add aria-label directly on the <svg role="img"> tag or add a <title> child element.
- Publish the site and validate with the axe browser extension.
How to fix role img alt on Adobe Commerce (Magento)
- Identify which template file renders the flagged element: use browser DevTools to find a unique class or ID, then search your theme under app/design/frontend/[Vendor]/[Theme]/ using grep -r 'role="img"' .
- Create or edit the relevant .phtml template file in your custom theme (never edit the core or parent theme directly).
- Add aria-label="<?= $block->escapeHtmlAttr(__('Description here')) ?>" to the element, using Magento's translation and escaping helpers so the label is translatable and safe.
- For SVG icon sprites (common in Luma and Hyva themes), locate the SVG sprite definition, add a <title id="icon-[name]">[Description]</title> inside each <symbol>, and update the <svg role="img" aria-labelledby="icon-[name]"> usage in templates.
- Run bin/magento setup:static-content:deploy and clear cache (bin/magento cache:clean) to see changes.
- Validate with axe DevTools browser extension on the frontend.
How to fix role img alt on Magento Open Source
- Same process as Adobe Commerce: locate the .phtml file in your custom theme using grep -r 'role="img"' app/design/.
- Override the template in your child theme and add aria-label or aria-labelledby as described above.
- Clear cache and redeploy static assets to test.
How to fix role img alt on PrestaShop
- In your PrestaShop back office, go to Design → Theme & Logo → your active theme.
- Use FTP or your hosting file manager to navigate to /themes/[your-theme]/templates/ and search for role="img" across .tpl (Smarty) files.
- Add aria-label="{l s='Description' d='Shop.Theme'}" to each flagged element, using PrestaShop's translation function so labels are translatable.
- Clear the Smarty cache under Advanced Parameters → Performance → Clear cache.
- Validate with the axe browser extension.
How to fix role img alt on Headless / Custom (I build in code)
- Search your component library/repository for all instances of role="img" (e.g. grep -r 'role="img"' src/).
- For each meaningful instance, add aria-label="[description]" as a prop or hardcoded attribute.
- For SVG components: add a <title> as the first child, assign it a unique id, and set aria-labelledby={titleId} on the <svg role="img"> element — this is the most robust pattern.
- For decorative instances: replace role="img" with aria-hidden="true" and remove role entirely.
- Write a unit test or linting rule (e.g. eslint-plugin-jsx-a11y rule 'no-aria-hidden-on-focusable') to prevent regressions.
- Run axe-core in your CI pipeline (e.g. via jest-axe or Playwright/axe) to catch future violations automatically.
Does your site have this issue?
Run a free SEOLZ scan to find role img alt — and every other issue — across your whole site in minutes.
Scan my site freeFrequently asked questions
What is Role img alt?
When a developer uses the HTML attribute `role="img"` on an element that isn't a native `<img>` tag — for example, an icon font character, an SVG group, a `<div>` containing a decorative graphic, or an emoji used as meaningful content — they are telling browsers and assistive technologies "treat this as an image." However, unlike a real `<img>` tag which has an `alt` attribute, these elements have no built-in place to put a text description. The `aria-label` attribute fills that gap: it provides the invisible text label that a screen reader will read aloud instead of the visual graphic. If `aria-label` (or an equivalent like `aria-labelledby`) is missing or empty, the element is announced to blind or low-vision users as an unlabelled image — or skipped entirely — making it meaningless.
Why does role img alt matter?
WCAG 2.1 Success Criterion 1.1.1 (Level A — the most basic accessibility level) requires that all non-text content has a text alternative. Failing this criterion means your store is inaccessible to the roughly 7–8 million people in the US alone who use screen readers, exposing you to legal risk under the ADA, Section 508, and equivalent laws in the EU (EAA 2025), UK, Australia, and Canada — accessibility lawsuits against ecommerce stores have increased sharply year-over-year. Beyond legal risk, unlabelled icons and graphics mean blind shoppers cannot understand product badges, trust seals, star ratings rendered as icon fonts, or navigation icons — directly harming conversions and checkout completion rates. Google also uses accessibility signals as part of its overall quality assessment, so a deeply inaccessible site can experience reduced crawl quality over time.
How do I fix role img alt?
Add a meaningful aria-label (or aria-labelledby) to every element with role="img" so screen readers can announce what the image represents.
Authoritative references
- How to fix this specific rule — Deque/axe (rule reference)
- WCAG 2 overview — W3C WAI
- Images & text alternatives — W3C WAI
- ARIA basics — MDN