Powered by
Names, roles & states
Text Grouped with role="text" Contains a Link or Button
Grouping text with `role="text"` flattens everything inside into plain words, so a link or button within it stops sounding like something you can use.
aria-textBest practiceBest practice — not a WCAG requirement, but it helps people all the same.
- Status
- SeriousSerious — Significant friction, or information that is lost.CurrentScanners run this rule today.
- Owner
- DesignDevTest
- Audit
- AutomatedA scanner finds it, and a clean scan means it's fixed.
Why it matters
role="text" is a non-standard role. Teams use it to stop VoiceOver reading a phrase in broken pieces, like a split-up price. It tells the screen reader to treat everything inside as one plain run of words.
If a link or button sits inside, it loses its role. Screen reader users hear words, not a control. Yet the Tab key still lands on it, so they reach something they can't identify or trust.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear the link's words as ordinary text, with no "link" or "button", so they don't know they can use it. | High impact |
| Low-vision users (magnification) | Affected only if they also use a screen reader, as many do. | Partial impact |
| Voice control users | Saying "click see terms" may fail, because the control can be hidden from their software. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | This is a best practice, not a WCAG 2.2 requirement on its own. But a control that a screen reader can't identify can still prompt complaints under Australia's Disability Discrimination Act. | Moderate impact |
| Conversion | It often wraps prices and offers. If the "See terms" or "Edit" control is hidden, people can stall at checkout. | Moderate impact |
| SEO | No search benefit either way — don't sell it as one. | Low impact |
| Brand trust | Controls that seem missing make the site feel broken to screen reader users. | Low impact |
| Cost to fix | Usually a small markup change: move the control outside the group. Fix it once in the shared component. | High impact |
Fixing it in code
A promo heading with a terms link
Don't
<h2><span role="text">Save 20% <a href="/terms">see terms</a></span></h2>A screen reader says: “Save 20% see terms, heading level 2”
Do
<h2><span role="text">Save 20%</span></h2>
<a href="/terms">See terms</a>A screen reader says: “Save 20%, heading level 2 … See terms, link”
Only plain text stays inside role="text", so the link keeps its role.
An order total with an Edit button
Don't
<p role="text">Total $49.95 <button>Edit</button></p>A screen reader says: “Total $49.95 Edit”
Do
<p><span role="text">Total $49.95</span> <button>Edit</button></p>A screen reader says: “Total $49.95 … Edit, button”
Wrapping just the price keeps it whole, and the button still sounds like a button.
Designer's handoff note
Keep links and buttons visually and structurally separate from prices or phrases that must be read as one piece.
In handover notes, say which words should be read together and which part is a control.
Quick test
Tool
VoiceOver (opens in a new tab) with Safari (on every Mac)
Checklist
- Pass
- You hear the control's name and its role, like "See terms, link".
- Fail
- You hear only the words, with no "link" or "button".
Check these at the same time
- An element has an ARIA role that doesn't suit it
aria-allowed-role - Hidden content can still receive keyboard focus
aria-hidden-focus
What a green scan still misses
A scanner finds focusable items inside role="text". It can't tell whether you need role="text" at all, or whether the grouped words now read sensibly — for that, listen.
Reference
- Rule ID
aria-text- Raised by
- axe-core: “"role=text" should have no focusable descendants”
- WCAG
- Best practice — not a WCAG requirement
- Last reviewed
- 14 October 2026