Using SVG Icons Accessibly

1. Why SVG icons are their own accessibility problem

SVG icons have replaced icon fonts in most modern frontends because they scale more sharply, can be recolored with CSS, and no longer require a symbol font to load. For accessibility, though, this switch brings a new trap: unlike an <img>, an <svg> element carries no enforced alt requirement, and without explicit labeling it simply delivers no text at all to assistive technology. Icon fonts were at least recognized by screen readers as text nodes, even if often with odd announcements. An unlabeled SVG, on the other hand, is either completely ignored or inconsistently read out as "graphic" with no meaning at all, depending on the browser and screen reader combination.

A typical Hyvä header packs several icon-only elements: the magnifying glass for search, the cart, the wishlist heart, and the hamburger menu for mobile navigation. If none of these are correctly labeled, a blind user cannot operate primary navigation or checkout at all. This directly affects two Level A success criteria: WCAG 1.1.1 Non-text Content and WCAG 4.1.2 Name, Role, Value, both part of the legally mandated minimum under the European Accessibility Act and EN 301 549.

2. Distinguishing meaningful from decorative icons

The most important step before any technical implementation is a simple question: does information get lost if the icon is removed without anything replacing it? If visible text already sits next to the icon, for example "Add to wishlist" right beside a heart symbol, the icon is purely decorative. The text carries the entire meaning, the icon only provides a visual shortcut for sighted users. If the icon stands alone, for instance as the only content of a button, it is meaningful and must supply an accessible name itself.

Purely stylistic elements such as bullet-point icons, dividers, or background patterns also count as decorative cases, as do icons that merely repeat information already conveyed by a nearby <h2> or badge text. A simple checklist helps in practice: is there visible text with the same meaning close by? Then it is decorative. Is the icon the only content of an interactive element, or does it convey information that appears nowhere else as text, such as a warning symbol for low stock? Then it is meaningful and needs its own name.

3. Hiding decorative icons correctly: aria-hidden and focusable

For decorative icons the rule is aria-hidden="true", so the screen reader removes the element entirely from the accessibility tree and does not announce it in addition to the accompanying text. Additionally, focusable="false" belongs on every SVG that sits inside an interactive element like <button> or <a>: older Internet Explorer and some Edge versions treat <svg> as focusable by default, which creates an extra, functionless tab stop per icon during keyboard navigation. Modern browsers are no longer affected, but the attribute costs nothing and does no harm.

A common mistake is leaving a <title> element inside a decorative SVG, often copied from an icon library. Even when aria-hidden="true" is set, the <title> element should then be removed or at least made semantically meaningless, because some browser extensions and tooltip scripts still display the title content as hover text, producing contradictory information.

<!-- WRONG: decorative icon is exposed to assistive technology, announced twice -->
<button type="button" class="inline-flex items-center gap-2">
  <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4"/>
  </svg>
  Add to cart
</button>

<!-- RIGHT: icon hidden from assistive technology, button label carries the meaning -->
<button type="button" class="inline-flex items-center gap-2">
  <svg class="w-4 h-4" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4"/>
  </svg>
  Add to cart
</button>

4. Naming meaningful icons: title, aria-label, role=img

When an SVG icon stands alone in the markup, without accompanying text, three techniques work together. First, a <title> element as the first child of the <svg>, connected via aria-labelledby to the title's ID. Second, role="img" on the <svg> element itself, because the implicit role of SVGs is inconsistent across browsers, and without an explicit role some screen readers treat the element as a pure graphics container with no announcement at all. Third, as an alternative to the <title> element, a direct aria-label on the <svg> when no visible title tooltip is desired.

It is important not to combine these three techniques arbitrarily: aria-label takes precedence over aria-labelledby in the accessible name computation, which in turn takes precedence over the <title> element. Setting all three with different text produces inconsistent announcements across screen readers. The most robust approach is either <title> plus aria-labelledby plus role="img", or aria-label alone plus role="img", but never both variants mixed with contradictory text.

<!-- Standalone meaningful icon: warning triangle without accompanying text -->
<svg
    role="img"
    aria-labelledby="warning-icon-title"
    class="w-5 h-5 text-amber-600"
    fill="currentColor"
    viewBox="0 0 20 20"
>
  <title id="warning-icon-title">Warning: low stock</title>
  <path d="M8.257 3.099c.765-1.36 2.72-1.36 3.486 0l6.516 11.59c.75 1.334-.213 3.011-1.743 3.011H3.485c-1.53 0-2.493-1.677-1.743-3.011l6.516-11.59zM10 13a1 1 0 100-2 1 1 0 000 2zm-.75-6.5a.75.75 0 011.5 0v3a.75.75 0 01-1.5 0v-3z"/>
</svg>

<!-- Alternative without a visible <title>: aria-label directly on the svg -->
<svg role="img" aria-label="Warning: low stock" class="w-5 h-5 text-amber-600" fill="currentColor" viewBox="0 0 20 20">
  <path d="M8.257 3.099c.765-1.36 2.72-1.36 3.486 0l6.516 11.59c.75 1.334-.213 3.011-1.743 3.011H3.485c-1.53 0-2.493-1.677-1.743-3.011l6.516-11.59z"/>
</svg>

5. Practical example: icon-only button with a correct accessible name

The wishlist heart button is the classic case of an icon-only button: no visible text, just a heart symbol that renders filled or outlined depending on state. The key principle is: when an SVG sits inside an interactive element like <button>, the accessible name should ideally live not on the SVG itself but on the enclosing button, for example via aria-label. The SVG then consistently gets aria-hidden="true", because otherwise, depending on the screen reader, both the button name and any SVG title present would be announced, making the output unnecessarily long or contradictory.

Just as important as the initial label is that the name changes together with the state. A plain toggle button that always says "wishlist" tells neither sighted nor blind users whether a product has already been saved. With Alpine.js the accessible name can be bound directly to the reactive state, so aria-label and aria-pressed always stay in sync with the visible heart color, instead of being maintained independently and drifting apart.

<!-- Hyva phtml: wishlist icon-only button, accessible name lives on the button -->
<button
    type="button"
    x-data="{ inWishlist: <?= $inWishlist ? 'true' : 'false' ?> }"
    x-on:click="inWishlist = !inWishlist; $dispatch('wishlist:toggle', { productId: <?= (int) $productId ?> })"
    x-bind:aria-pressed="inWishlist.toString()"
    x-bind:aria-label="inWishlist ? 'Remove from wishlist' : 'Add to wishlist'"
    class="inline-flex items-center justify-center w-11 h-11 rounded-full hover:bg-slate-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-zinc-800"
>
    <svg
        class="w-5 h-5"
        x-bind:fill="inWishlist ? 'currentColor' : 'none'"
        aria-hidden="true"
        focusable="false"
        stroke="currentColor"
        viewBox="0 0 24 24"
    >
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
              d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z"/>
    </svg>
</button>

6. Inline SVG vs. SVG sprite: accessibility differences

SVG sprites, where a central sprite sheet bundles multiple <symbol> definitions and individual icons are referenced via <use xlink:href="#icon-heart">, are attractive from a performance perspective: a single file instead of many individual inline SVGs in the markup. There is an accessibility subtlety that is often overlooked: a <title> element inside a <symbol> in the sprite file is not reliably picked up as the accessible name by some screen readers and browsers when instantiated via <use>, especially when the sprite is loaded as an external file rather than sitting inline in the document.

The robust solution is to not maintain the label in the <symbol> definition, but directly on the <svg> or <use> element at each point of use. Every instance of an icon can then get its own, context-dependent name, for example "Add to wishlist" in one place and "Already on wishlist" in another, even though both reference the same <symbol>. This instance-based labeling works reliably across all relevant browser and screen reader combinations, while sprite-internal titles do not guarantee that.

7. Focus visibility and color contrast for icons

Icon-only buttons are usually smaller than text-based buttons and therefore need special attention for two criteria: target size and color contrast. WCAG 2.5.8 Target Size (Minimum) requires a clickable area of at least 24 by 24 CSS pixels; in practice, significantly more is recommended for touch input, with 44 by 44 pixels of padding around the visually smaller icon being common. This keeps the button reliably tappable even with a shaky hand or a pointing device instead of a finger, without the icon itself needing to grow visually.

For meaningful icons, WCAG 1.4.11 Non-text Contrast also applies: the icon must achieve a contrast of at least 3:1 against its background, just like a form field border or a focus indicator. fill="currentColor" or stroke="currentColor" is the most reliable technique here, because the icon automatically inherits the text color of its surrounding context, including dark mode adjustments, instead of carrying a hardcoded color that suddenly delivers too little contrast after a theme switch. The focus ring itself must also never become visible only through a color change, but needs a genuine outline or box-shadow.

/* Icon color follows the surrounding text color, including dark mode */
.icon-button svg {
  color: currentColor;
}

/* Minimum 44x44px hit area even though the visual icon itself is smaller */
.icon-button {
  min-width: 44px;
  min-height: 44px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

/* Visible focus ring, never rely on a color change alone for focus state */
.icon-button:focus-visible {
  outline: 2px solid #18181b;
  outline-offset: 2px;
}

/* Non-text contrast: meaningful icons need at least 3:1 against their background */
.icon-button svg {
  color: #3f3f46; /* passes 3:1 against a white background */
}

8. Testing icons: screen readers, axe-core, and keyboard

Automated tools like axe-core or Lighthouse reliably detect missing accessible names on buttons and links, essentially checking whether any name can be computed at all. What they cannot evaluate is whether that name is actually meaningful or changes correctly with state, for example during the wishlist toggle. That is exactly why every icon test needs a manual check as well: tab to the button with the keyboard, listen to the announcement with NVDA under Firefox or VoiceOver under Safari, and verify that name, role, and state (such as "pressed" for aria-pressed="true") are read out correctly and clearly.

For CI pipelines, it is worth running axe-core automatically against key page types via Playwright or Cypress and failing the build on violations, supplemented with targeted assertions for dynamic states that axe alone cannot check. This way, regressions, such as an accidentally removed aria-hidden after an icon library update, become visible before deployment instead of only in production through user complaints.

// Playwright + axe-core: fail the build on icon accessibility violations
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('wishlist icon buttons have an accessible name', async ({ page }) => {
  await page.goto('/catalog/product/view/id/123');

  const results = await new AxeBuilder({ page })
    .include('.icon-button')
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);

  // Manual assertion: accessible name must change together with the state
  const button = page.locator('button[aria-pressed]').first();
  await expect(button).toHaveAttribute('aria-label', 'Add to wishlist');
  await button.click();
  await expect(button).toHaveAttribute('aria-label', 'Remove from wishlist');
});

9. Common SVG icon mistakes compared side by side

Most SVG icon problems trace back to a handful of recurring patterns. The following overview shows the most common mistakes and the correct implementation side by side.

What stands out in the table: in almost every case, the problem is not the SVG markup itself, but a missing or misplaced label. A single consistently applied pattern, hide the icon decoratively or give the icon its own name, covers the vast majority of practical cases without requiring every icon use to be rethought individually.

10. Summary

Using SVG icons accessibly always starts with the same decision: is the icon decorative, because visible text already carries the meaning, or is it meaningful, because it stands alone? Decorative icons should consistently be removed from the accessibility tree with aria-hidden="true" and focusable="false". Meaningful icons need their own name via <title> plus aria-labelledby, a direct aria-label, and in both cases role="img", so the role stays consistent across browsers.

For icon-only buttons like the wishlist heart, the accessible name should ideally live on the button itself, not on the SVG, and change dynamically with the state together with aria-pressed. SVG sprites need labeling per point of use rather than in the shared <symbol>. Focus visibility, sufficient color contrast via currentColor, and a minimum target size of 44 by 44 pixels round out a genuinely accessible icon system that can be reliably verified with axe-core, keyboard, and screen reader tests.

11. FAQ: Using SVG Icons Accessibly