WAI-ARIA splits its aria-* attributes into two groups: states, which change
as the user interacts, and properties, which are usually set once. Both carry
a defined value type, and some are global — valid on any element. This is a
searchable offline reference for every standard attribute from WAI-ARIA 1.2.
How it works
Each attribute is listed with four facts that decide whether your markup is valid:
- Value type —
true/false, a tristate (true/false/mixed), an enumerated token, an integer or number, an id reference / id reference list, or a free string. Out-of-range values are ignored by assistive technology. - State vs property — states (
aria-checked,aria-expanded) are expected to change during use; properties (aria-label,aria-haspopup) generally do not. - Global — global attributes apply to every element regardless of role
(
aria-label,aria-hidden,aria-live); non-global ones are only valid on roles that support them. - Default — the implicit value when the attribute is absent or empty.
Value types explained
Getting the value type right prevents attributes from being silently ignored by screen readers:
| Type | Example attributes | Allowed values |
|---|---|---|
true/false | aria-disabled, aria-readonly | The strings "true" or "false" only |
tristate | aria-checked, aria-pressed | "true", "false", or "mixed" |
token | aria-live, aria-haspopup, aria-orientation | A fixed enumerated list per attribute |
integer | aria-level, aria-rowspan, aria-colindex | A whole number within a defined range |
number | aria-valuenow, aria-valuemin, aria-valuemax | Any numeric value |
ID reference | aria-activedescendant, aria-errormessage | A single element ID |
ID reference list | aria-labelledby, aria-describedby, aria-controls | Space-separated element IDs |
string | aria-label, aria-placeholder, aria-roledescription | Any text |
Detailed examples
aria-checked (tristate state): on a role="checkbox" it must be present and set to true, false, or mixed. The mixed value is for checkboxes that control a group where some but not all children are checked. By contrast, aria-pressed on a role="button" also takes tristate — use mixed only if the button has genuinely indeterminate state, such as a formatting button that applies to text with mixed bold/non-bold spans.
aria-labelledby vs aria-label: aria-labelledby points to existing visible text by ID and is preferred because it reuses content already on the page. aria-label provides an invisible label string and is the fallback when no visible text can serve as the name. Both are global properties, so they work on any element regardless of role.
aria-live (token property): takes one of three tokens — off (default, no announcements), polite (announces after user finishes current interaction), or assertive (interrupts immediately). Overuse of assertive creates a noisy, frustrating experience for screen-reader users.
Common mistakes
- Using
aria-hidden="true"on a focusable element — keyboard users can still reach it, but screen readers will not announce it, causing a confusing mismatch. - Writing
aria-disabledwithout also preventing the action — the attribute tells AT the element is disabled but does not prevent clicks or keyboard events the way the HTMLdisabledattribute does. - Setting
aria-expandedwithout toggling it — the attribute is a state and must be updated in JavaScript each time the panel opens or closes. - Applying non-global attributes to roles that don’t support them —
aria-checkedon arole="link"is meaningless and ignored.
Notes
- Boolean ARIA attributes take the strings
"true"/"false", not the presence/absence pattern of HTML boolean attributes likedisabled. aria-hidden="true"removes an element and its subtree from the accessibility tree — never put it on a focusable element.- This reference lists the standard attributes; per-role required and supported sets are covered in the ARIA Role Reference.