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.
On this page
- Which markup to use
- What our test found
- Decorative icons
- Icon-only buttons and links
- Standalone icons: role=img, title or aria-labelledby
- Library defaults: what 8 React packages render
- Sprites and img tags
- WCAG 2.2 rules that apply to icons
- Target size: the real 24 pixel rule
- Contrast and color blindness
- Forced colors and high contrast
- How to test your icons
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 is | Markup |
|---|---|
| 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:
| Markup | Exposed as | axe |
|---|---|---|
<svg> with no attributes | image, no name | Pass |
aria-hidden="true" | Not exposed | Pass |
aria-label="Search", no role | image "Search" | Pass |
<title> only, no role | image "Search" | Pass |
role="img", no name | image, no name | Fail: svg-img-alt |
role="img" + aria-label | image "Search" | Pass |
role="img" + <title> | image "Search" | Pass |
role="img" + aria-labelledby pointing to <title> | image "Search" | Pass |
aria-hidden="true" + role="img" + aria-label | Not exposed | Pass |
<img alt="Search"> | image "Search" | Pass |
<img alt=""> | Not exposed | Pass |
Icons inside buttons and links:
| Markup | Exposed as | axe |
|---|---|---|
| Button, bare SVG | button, no name, with an unnamed image inside | Fail: button-name |
Button, aria-hidden SVG | button, no name | Fail: button-name |
Button aria-label, aria-hidden SVG | button "Search" | Pass |
Button aria-label, bare SVG | button "Search", with an unnamed image inside | Pass |
Button, SVG role="img" + aria-label | button "Search", with image "Search" inside | Pass |
Button, SVG aria-label with no role | button "Search", with image "Search" inside | Pass |
Button, SVG <title> | button "Search", with image "Search" inside | Pass |
Button, aria-hidden SVG + visually hidden text | button "Search" | Pass |
Button title attribute, aria-hidden SVG | button "Search" | Pass |
Button, <img alt="Search"> | button "Search", with image "Search" inside | Pass |
Button aria-label="Search", SVG labelled "Magnifier" | button "Search", with image "Magnifier" inside | Pass |
| Button with visible "Search", SVG labelled "Magnifier" | button "Magnifier Search" | Pass |
Button with visible "Search", aria-hidden SVG | button "Search" | Pass |
Link aria-label, aria-hidden SVG | link "Search" | Pass |
| Link, bare SVG | link, no name, with an unnamed image inside | Fail: link-name |
| 16px button, no padding, no neighbor | button "Search" | Pass |
Three results in those tables pass the scan and are still wrong:
- 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. aria-hiddenplus a label.aria-hiddenwins, and the label does nothing. You wrote the name and nobody gets it.- 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 it | When to use it | What to watch |
|---|---|---|
aria-label | Default choice | No tooltip |
<title> | You also want a hover tooltip | The title must be the first child of the SVG |
aria-labelledby + <title id> | The name lives in the markup, or several elements share it | Each 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.
| Package | Default output | With aria-label | Name prop |
|---|---|---|---|
| lucide-react 1.68.0 | aria-hidden="true" | Removes aria-hidden, label works | title gives no output |
| @mui/icons-material 9.5.0 | aria-hidden="true" | Stays hidden | titleAccess adds role="img" and <title>, removes aria-hidden |
| @heroicons/react 2.2.0 | aria-hidden="true" | Stays hidden | title adds <title>, stays hidden |
| @phosphor-icons/react 2.1.10 | Nothing | Passes through | alt adds <title> |
| @tabler/icons-react 3.50.0 | Nothing | Passes through | title adds <title> |
| @remixicon/react 4.9.0 | Nothing | Passes through | title gives no output |
| react-icons 5.7.0 | Nothing | Passes through | title adds <title> |
| @fortawesome/react-fontawesome 3.5.0 | role="img", aria-hidden="true" | Sets aria-hidden="false", label works | title 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-labelalone does nothing. UsetitleAccessin MUI. In Heroicons, setaria-hiddento 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
| Criterion | Level | What it means for an icon |
|---|---|---|
| 1.1.1 Non-text content | A | A meaningful icon has a text name, a decorative one is hidden |
| 1.4.1 Use of color | A | Color is not the only signal |
| 1.4.11 Non-text contrast | AA | 3:1 against adjacent colors when the icon is needed to understand the page |
| 2.4.7 Focus visible | AA | Keyboard focus can be seen on icon buttons |
| 2.5.3 Label in name | A | The accessible name contains the visible text |
| 2.5.8 Target size (minimum) | AA | Targets are at least 24 by 24 CSS pixels, with exceptions |
| 4.1.2 Name, role, value | A | Controls 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:
| Layout | axe target-size |
|---|---|
| Two 16px buttons touching | Fail |
| Two 16px buttons, 8px gap | Pass |
| Two 16px buttons, 12px gap | Pass |
| Two 24px buttons (16px icon, 4px padding) touching | Pass |
| One 16px button with no neighbor | Pass |
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.
![]()
| Coloring method | Dark theme | Light theme |
|---|---|---|
currentColor | 21.00 | 21.00 |
Hardcoded #111 | 1.11 | 18.88 |
Hardcoded #fff | 21.00 | 1.00 |
CSS mask + background: currentColor | 1.00 | 1.00 |
CSS background-image with a dark stroke | 1.00 | 21.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
- Read the accessibility tree. In Chrome DevTools, open Elements, then the Accessibility pane, and check the name and role of each icon control.
- Run axe, then look past it. It catches unnamed buttons and links, but it passed the bare SVG and the hidden label above.
- Use only the keyboard. Tab through the page. Every icon control should show focus and work with Enter or Space.
- Turn on a screen reader. NVDA on Windows and VoiceOver on Mac are free. Listen for "button" with no name.
- 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?
Do I need role=img if the SVG has aria-label?
Should the aria-label go on the button or the SVG?
Is title enough to make an SVG accessible?
Does a clean axe report mean my icons are accessible?
What size must an icon button be under WCAG 2.2?
How do I make SVG icons work in Windows high contrast mode?
Related posts