React Reference ยท Props and Attributes
React aria-* attributes
How aria-* attributes work in React: hyphenated names, string values for booleans, role, live regions and common mistakes like ariaLabel.
ARIA attributes describe the role, state and properties of an element to assistive technology such as screen readers. In React almost every DOM attribute is camelCase (className, tabIndex), but aria-* attributes are the exception: they keep their hyphens, exactly as in HTML. The same goes for data-*.
<button aria-label="Close dialog" aria-expanded={open} aria-controls="menu"> X </button>
The role attribute is a normal lowercase prop. Use real semantic elements first (<button>, <nav>, <dialog>); add ARIA only when HTML has no element that fits.
Try it
A live region announces changes without moving focus. Here role="status" (an implicit aria-live="polite") reports how many items are in a cart.
Syntax
<element role="..." aria-label="..." aria-hidden={true} aria-describedby="id" />
| Name | Description |
|---|---|
role |
The ARIA role, for example "status", "alert", "tablist". Lowercase, no hyphen needed. |
aria-label |
A string that names the element when it has no visible text. |
aria-labelledby, aria-describedby |
Space-separated ids of the elements that label or describe this one. |
aria-expanded, aria-pressed, aria-selected, aria-checked, aria-current |
State attributes. |
aria-hidden |
Hides the element (and its subtree) from assistive technology without hiding it visually. |
Value rules: React writes aria-* values as strings. aria-expanded={true} becomes aria-expanded="true" and aria-expanded={false} becomes aria-expanded="false", which is what ARIA expects. null or undefined removes the attribute.
Usage notes
- No camelCase. Writing
ariaLabelis a mistake: React warns "Invalid ARIA attributeariaLabel. Did you meanaria-label?" and does not apply it. - Unknown names warn too.
aria-labellis reported in development as an invalid ARIA attribute. - First rule of ARIA: use a native element when one exists. A
<button>already has a role, focus and keyboard support; a<div role="button">needs all of that added by hand. - Do not put
aria-hidden="true"on a focusable element. Keyboard users can still reach it, but screen readers will not announce it. - Unique ids. For
aria-controlsandaria-labelledby, generate ids withuseIdinstead of hard-coding them, so components can be used several times on a page. - Test it. Automated checks find many problems, but trying a screen reader and the keyboard finds more.