Skip to content
Tutorials Center
My learning

Topics

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-*.

JSX
<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 disclosure button with aria-expanded

A live region announces changes without moving focus. Here role="status" (an implicit aria-live="polite") reports how many items are in a cart.

A polite live region

Syntax

JSX
<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 ariaLabel is a mistake: React warns "Invalid ARIA attribute ariaLabel. Did you mean aria-label?" and does not apply it.
  • Unknown names warn too. aria-labell is 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-controls and aria-labelledby, generate ids with useId instead 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.