ADA Compliance Professionals

    SVG img role needs a text alternative

    Last updated:

    Who it helps:
    Blind
    Standard:
    WCAG 2.2 Level A

    Related Guides

    SVG with img, graphics-document, or graphics-symbol role require an accessible text alternative

    Every inline SVG assigned the img, graphics-document, or graphics-symbol role must expose a meaningful accessible name.

    This comes up with icons, logos, charts, and decorative flourishes added as inline SVG. It primarily affects screen reader users and anyone relying on alternative output like braille.

    Why It Matters

    Without a text alternative, assistive technologies announce nothing useful. Users who cannot see the graphic miss information or context, such as what a button icon does or what a chart shows.

    Consistent names also benefit speech input users who issue voice commands and people with cognitive disabilities who use summaries. Proper naming supports WCAG 2.2 success criterion 1.1.1 (Non-text Content).

    Common Causes

    • Inline SVG used as an icon with role="img" but no <title>, aria-label, or aria-labelledby
    • Assuming the file name, tooltip, or nearby text will be used as the accessible name
    • Adding multiple naming methods (e.g., <title> and aria-label) causing duplicate announcements
    • Marking decorative SVG with a role but forgetting to hide it from assistive tech
    • Using aria-labelledby with IDs that do not exist or are duplicated
    • Making non-interactive SVG focusable via tabindex or default browser behavior

    How to Fix

    1. Determine purpose
      • Informational (single concept): treat as one image and name it.
      • Complex (chart/diagram): provide a short name and a longer description.
      • Decorative: hide it from assistive tech.
    2. Simple informational SVG (recommended pattern)
      • Set role="img" on the <svg>.
      • Provide exactly one accessible name method:
      • Preferred: include a <title id> inside the SVG and reference it with aria-labelledby on the SVG.
      • Alternative: aria-label on the SVG for a short, programmatic name.
      • Ensure the SVG is not focusable: remove tabindex and set focusable="false" if needed.
    3. Complex graphics (charts, diagrams)
      • Use role="graphics-document" on the <svg> when the graphic conveys multiple parts.
      • Provide a short accessible name (aria-labelledby or aria-label).
      • Provide a longer description:
      • Use a <desc id> inside the SVG and point to it with aria-describedby, or
      • Reference visible nearby text via aria-describedby, or link to a detailed explanation.
    4. Decorative SVG
      • If purely decorative, do not assign img/graphics roles. Add aria-hidden="true" on the SVG, or use role="presentation" so it is ignored by assistive tech.
    5. Avoid conflicts
      • Use only one naming method to prevent duplicate announcements.
      • Ensure any IDs used by aria-labelledby/aria-describedby are unique and present in the DOM.

    Recommendation: Prefer <title> + aria-labelledby for portability across user agents. Use aria-label for quick, inline naming. Avoid relying solely on the HTML title attribute as support varies.

    How to Test

    Keyboard

    • Tab through the page. Non-interactive SVG should not receive focus. If it does, remove tabindex and set focusable="false".

    Screen reader

    • Desktop (NVDA/JAWS + Chrome/Firefox):
    • Navigate to the SVG. Confirm it announces once as "graphic" (or similar) followed by the expected name.
    • Ensure there are no duplicate or empty announcements.
    • macOS VoiceOver + Safari:
    • VO+Right Arrow to the SVG. Confirm the same single, accurate name is read.

    Mobile/touch

    • iOS VoiceOver / Android TalkBack:
    • Explore by touch over the SVG. Confirm the label is announced once and matches the visible purpose.

    Accessibility tree

    • Use browser devtools Accessibility pane. Verify:
    • Role is img or graphics-document/graphics-symbol as intended.
    • Name is present and correct.
    • Description appears when using aria-describedby for complex graphics.

    Good Example

    HTML
    <svg role="img" aria-labelledby="logo-title" focusable="false" viewBox="0 0 100 100">
  <title id="logo-title">Green leaf company logo</title>
  <path d="M10 60 C 30 10, 70 10, 90 60 C 70 80, 30 80, 10 60 Z" fill="#12a150" />
</svg>

    Bad Example

    HTML
    <svg role="img" tabindex="0" viewBox="0 0 24 24">
  <!-- No title, no aria-label/labelledby; incorrectly focusable -->
  <path d="M3 12h18" stroke="#000" />
</svg>

    Quick Checklist

    • Role set appropriately: img for single images; graphics-document for complex graphics; hide decorative SVG
    • Exactly one accessible name method: <title> + aria-labelledby or aria-label
    • Names are concise, accurate, and not duplicated by multiple methods
    • For complex graphics, provide a longer description via <desc> or aria-describedby
    • Non-interactive SVG is not focusable (no tabindex; focusable="false")
    • aria-labelledby/aria-describedby reference valid, unique IDs
    • Verified in the accessibility tree and with at least one screen reader