Accessible SVG Icons: aria-label, role=img and aria-hidden

Hide decorative SVG icons with aria-hidden, name the button on icon-only controls, use role=img on standalone icons. Tested: 27 patterns, 8 React libraries.

Amit Yadav
15 min read
On this page

Hide an SVG icon with aria-hidden="true" when text beside it already says the same thing. When the icon is the only content of a button or link, put the name on the button or link, and when it stands alone and carries meaning, use role="img" with aria-label.

The rules are short, but the failures are quiet. We ran 27 markup patterns through Chromium's accessibility tree and axe-core, and rendered a search icon from 8 React libraries. An automated scan missed several of the problems, and two libraries hide your aria-label from screen readers.

Quick answer

  • Decorative icon: set aria-hidden to true on the SVG.
  • Icon-only button or link: aria-label on the control, aria-hidden on the SVG.
  • Standalone icon with meaning: role=img plus aria-label.
  • Icon library: check what it renders. In MUI and Heroicons, aria-label alone leaves the icon hidden.
  • Color: use currentColor. A CSS mask icon disappeared in forced colors mode in our test.

Which markup to use

The icon isMarkup
Beside text that says the same thing<svg aria-hidden="true">
The only content of a button<button aria-label="Search"> around <svg aria-hidden="true">
The only content of a link<a href="/search" aria-label="Search"> around <svg aria-hidden="true">
On its own and carries meaning<svg role="img" aria-label="Saved">
An external file<img src="search.svg" alt="Search">, or alt="" if decorative

Name what the control does, not what the icon shows. A screen reader user needs "Search" or "Delete draft", not "Magnifying glass" or "Trash can".

What our test found

We read the computed accessibility tree in Chromium 153 and ran axe-core 4.14.0 on each pattern, on 2026-11-05. This shows what the browser exposes to assistive technology. We did not test Firefox, Safari or a real screen reader, so treat it as a first check and not as proof of how a user hears the page.

Icons on their own:

MarkupExposed asaxe
<svg> with no attributesimage, no namePass
aria-hidden="true"Not exposedPass
aria-label="Search", no roleimage "Search"Pass
<title> only, no roleimage "Search"Pass
role="img", no nameimage, no nameFail: svg-img-alt
role="img" + aria-labelimage "Search"Pass
role="img" + <title>image "Search"Pass
role="img" + aria-labelledby pointing to <title>image "Search"Pass
aria-hidden="true" + role="img" + aria-labelNot exposedPass
<img alt="Search">image "Search"Pass
<img alt="">Not exposedPass

Icons inside buttons and links:

MarkupExposed asaxe
Button, bare SVGbutton, no name, with an unnamed image insideFail: button-name
Button, aria-hidden SVGbutton, no nameFail: button-name
Button aria-label, aria-hidden SVGbutton "Search"Pass
Button aria-label, bare SVGbutton "Search", with an unnamed image insidePass
Button, SVG role="img" + aria-labelbutton "Search", with image "Search" insidePass
Button, SVG aria-label with no rolebutton "Search", with image "Search" insidePass
Button, SVG <title>button "Search", with image "Search" insidePass
Button, aria-hidden SVG + visually hidden textbutton "Search"Pass
Button title attribute, aria-hidden SVGbutton "Search"Pass
Button, <img alt="Search">button "Search", with image "Search" insidePass
Button aria-label="Search", SVG labelled "Magnifier"button "Search", with image "Magnifier" insidePass
Button with visible "Search", SVG labelled "Magnifier"button "Magnifier Search"Pass
Button with visible "Search", aria-hidden SVGbutton "Search"Pass
Link aria-label, aria-hidden SVGlink "Search"Pass
Link, bare SVGlink, no name, with an unnamed image insideFail: link-name
16px button, no padding, no neighborbutton "Search"Pass

Three results in those tables pass the scan and are still wrong:

  1. A bare SVG. It is exposed as an image with no name, and axe stays silent because the SVG has no role="img" for the rule to check. A clean axe report does not mean your icons are correct.
  2. aria-hidden plus a label. aria-hidden wins, and the label does nothing. You wrote the name and nobody gets it.
  3. A named icon beside visible text. The button name became "Magnifier Search". The extra word is noise, so hide the icon when the text already does the job.

Decorative icons

If you remove the icon and the sentence still makes sense, it is decorative.

<button type="button">
  <svg aria-hidden="true" viewBox="0 0 24 24"><!-- paths --></svg>
  Save
</button>

Add aria-hidden="true" yourself. An SVG with no attributes is not ignored: Chromium exposes it as an unnamed image.

Do not put aria-hidden on anything that can take focus. That removes a focusable element from the accessibility tree, and a keyboard user lands on something a screen reader cannot describe.

Icon-only buttons and links

Put the name on the interactive element. It is the element a user reaches, and the name then does not depend on how the SVG is written.

<button type="button" aria-label="Search">
  <svg aria-hidden="true" viewBox="0 0 24 24"><!-- paths --></svg>
</button>

Visually hidden text gave the same name in our test. It suits sites that auto-translate their pages, because some browser translation tools miss aria-label. We did not test translation, so check this on your own stack.

<button type="button">
  <svg aria-hidden="true" viewBox="0 0 24 24"><!-- paths --></svg>
  <span class="sr-only">Search</span>
</button>

A title attribute on the button also produced a name, but a tooltip does not replace a label: touch users and many keyboard users never see it. Use aria-label or hidden text.

Toggle buttons: keep the label fixed and change the state, for example aria-label="Mute" aria-pressed="true". If the label changes instead ("Mute" to "Unmute"), do not also add aria-pressed, or a user hears the state twice.

Label in name: when a button shows text, its aria-label must contain that text (WCAG 2.5.3). A voice control user says what they see. "Save" and aria-label="Save draft" works. "Save" and aria-label="Store file" does not.

Standalone icons: role=img, title or aria-labelledby

Use this when an icon carries meaning and has no control or text around it, such as a status mark in a table cell.

<svg role="img" aria-label="Payment failed" viewBox="0 0 24 24">
  <!-- paths -->
</svg>

The default mapping for svg in the SVG accessibility mappings is graphics-document, so role="img" tells assistive technology to treat the icon as one image. See MDN on the img role for the general rule. It requires a name: role="img" with none was the one standalone pattern axe failed.

Way to name itWhen to use itWhat to watch
aria-labelDefault choiceNo tooltip
<title>You also want a hover tooltipThe title must be the first child of the SVG
aria-labelledby + <title id>The name lives in the markup, or several elements share itEach id must be unique on the page

All three gave the same name in Chromium, so aria-labelledby is not needed for an ordinary icon. If you use it, duplicate ids are the risk: a repeated icon with id="title" resolves to the first match. In React, build the id with useId().

Library defaults: what 8 React packages render

Many teams never write the SVG by hand, so the package decides. We server-rendered a search icon from each package and read the root <svg>, on 2026-11-05, at the versions shown.

PackageDefault outputWith aria-labelName prop
lucide-react 1.68.0aria-hidden="true"Removes aria-hidden, label workstitle gives no output
@mui/icons-material 9.5.0aria-hidden="true"Stays hiddentitleAccess adds role="img" and <title>, removes aria-hidden
@heroicons/react 2.2.0aria-hidden="true"Stays hiddentitle adds <title>, stays hidden
@phosphor-icons/react 2.1.10NothingPasses throughalt adds <title>
@tabler/icons-react 3.50.0NothingPasses throughtitle adds <title>
@remixicon/react 4.9.0NothingPasses throughtitle gives no output
react-icons 5.7.0NothingPasses throughtitle adds <title>
@fortawesome/react-fontawesome 3.5.0role="img", aria-hidden="true"Sets aria-hidden="false", label workstitle gave no <title> in our render

Two results matter:

  • Half of them expose a bare icon. Phosphor, Tabler, Remix and react-icons add no aria-hidden, so a decorative icon becomes an unnamed image unless you hide it.
  • In MUI and Heroicons, aria-label alone does nothing. Use titleAccess in MUI. In Heroicons, set aria-hidden to false yourself: this rendered correctly in both packages.
// Works the same in all 8: name the control, hide the icon
<button type="button" aria-label="Search">
  <SearchIcon aria-hidden="true" />
</button>

// Standalone icon in Heroicons or MUI
<MagnifyingGlassIcon role="img" aria-label="Search" aria-hidden={false} />

For a wrapper that keeps these rules in one place, see how to use SVG icons in React. Font Awesome documents its own rules in its accessibility guide, and MUI in its icon docs.

Raw SVG files: we sampled 100 evenly spaced icons from each of the 20 top packs on our pack pages. All 2,000 paint with currentColor and none includes a <title>, so the name is always yours to add. We did not sample color packs such as flags and emoji.

Sprites and img tags

With an <img>, the file's own markup is not read as content, so alt is the only name. A <title> inside the file does not replace it.

With a sprite, put the attributes on the outer SVG:

<svg aria-hidden="true" width="20" height="20">
  <use href="/sprite.svg#search"></use>
</svg>

Use the same rules as inline SVG: hide it and name the control, or give the outer SVG role="img" and a name. We did not run sprites through the test above. The trade-offs between the formats are in icon fonts vs sprites vs inline SVG.

WCAG 2.2 rules that apply to icons

CriterionLevelWhat it means for an icon
1.1.1 Non-text contentAA meaningful icon has a text name, a decorative one is hidden
1.4.1 Use of colorAColor is not the only signal
1.4.11 Non-text contrastAA3:1 against adjacent colors when the icon is needed to understand the page
2.4.7 Focus visibleAAKeyboard focus can be seen on icon buttons
2.5.3 Label in nameAThe accessible name contains the visible text
2.5.8 Target size (minimum)AATargets are at least 24 by 24 CSS pixels, with exceptions
4.1.2 Name, role, valueAControls expose a name and state

Target size: the real 24 pixel rule

WCAG 2.5.8 asks for 24 by 24 CSS pixels, not 44. The 44 figure is the older, stricter AAA criterion 2.5.5. The rule has five exceptions: spacing, an equivalent control, inline targets, user agent controls and essential presentation.

The spacing exception shows up in axe:

Layoutaxe target-size
Two 16px buttons touchingFail
Two 16px buttons, 8px gapPass
Two 16px buttons, 12px gapPass
Two 24px buttons (16px icon, 4px padding) touchingPass
One 16px button with no neighborPass

Padding is the simple fix: the icon can stay at 16px while the button reaches 24px or more. A larger target is still better on touch screens, and our icon size guidelines give sizes per platform.

Keep focus visible as well:

.icon-button:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 2px;
}

Contrast and color blindness

WCAG 1.4.11 asks for 3:1 against adjacent colors when an icon is needed to understand the page or use a control. It does not apply when visible text carries the same information, when the icon is purely decorative, or when the control is disabled.

Color alone also fails (WCAG 1.4.1). Red and green status dots can look the same to a user with red-green color blindness, so change the shape as well:

Add a text label when the status matters. A check mark and a cross are clear to most users, and "Failed" is clear to everyone.

Forced colors and high contrast

Windows Contrast Themes replace site colors, and the way you color an icon decides whether it survives. We rendered one icon five ways in Chromium's forced-colors emulation and measured the highest contrast each one reached against the background.

Five search icons on a dark forced colors background. The currentColor icon and the mask icon with forced-color-adjust none are clear. The hardcoded dark, plain mask and background-image icons are hard to see or invisible.

Coloring methodDark themeLight theme
currentColor21.0021.00
Hardcoded #1111.1118.88
Hardcoded #fff21.001.00
CSS mask + background: currentColor1.001.00
CSS background-image with a dark stroke1.0021.00

Only currentColor kept full contrast in both. A ratio of 1.00 means the icon is invisible. Emulation is not a real Windows machine, so check a Contrast Theme before you ship anything important.

The mask result catches teams out: forced colors removes the background that paints the icon. This restored 21.00 in both themes in our test (preserve-parent-color gave the same result):

.mask-icon {
  forced-color-adjust: none;
}

Multi-color logos and flags are the exception, and they usually need their own treatment. For single-color icons, see how to change SVG icon color with CSS.

How to test your icons

  1. Read the accessibility tree. In Chrome DevTools, open Elements, then the Accessibility pane, and check the name and role of each icon control.
  2. Run axe, then look past it. It catches unnamed buttons and links, but it passed the bare SVG and the hidden label above.
  3. Use only the keyboard. Tab through the page. Every icon control should show focus and work with Enter or Space.
  4. Turn on a screen reader. NVDA on Windows and VoiceOver on Mac are free. Listen for "button" with no name.
  5. Test forced colors. In DevTools, open the Rendering panel and emulate forced-colors: active.

A role query in your test suite catches a missing name on every run:

await page.getByRole('button', { name: 'Search' }).click();

The query fails if the button has no accessible name, which also makes the test read like the user's task.

Should I use role=img or aria-hidden on an SVG icon?
Use aria-hidden=true when the icon is decorative or text beside it says the same thing. Use role=img with aria-label when the icon carries meaning on its own. Do not combine them: in our test aria-hidden won and the label was lost.
Do I need role=img if the SVG has aria-label?
In our Chromium test, aria-label with no role still gave an image with the right name. Adding role=img makes the intent explicit and lets axe check for a missing name, so it is worth adding on standalone icons.
Should the aria-label go on the button or the SVG?
On the button. Then set aria-hidden=true on the SVG. The name stays correct whichever icon or library you swap in. A named SVG inside a button also gave a named button in our test, but it leaves an extra image node inside the button.
Is title enough to make an SVG accessible?
It gave the correct name in Chromium, with and without role=img. It also shows a hover tooltip, which you may not want. Use aria-label by default, and title when you want the tooltip.
Does a clean axe report mean my icons are accessible?
No. axe passed a bare SVG with no name, an aria-hidden icon whose label was lost, and a button named Magnifier Search. It finds unnamed buttons and links well, but you still need to read the accessibility tree and try a screen reader.
What size must an icon button be under WCAG 2.2?
At least 24 by 24 CSS pixels under criterion 2.5.8, level AA, with exceptions such as enough spacing around a smaller target. The 44 pixel figure comes from the stricter AAA criterion 2.5.5.
How do I make SVG icons work in Windows high contrast mode?
Paint them with currentColor. It kept full contrast in both dark and light forced colors in our test. Hardcoded colors and CSS background images failed in at least one theme, and a CSS mask needs forced-color-adjust: none.

Related posts

Share this post