ARIA state
aria-disabled
Says a control is present but not available. Unlike the disabled attribute, it stays focusable, so people can still find out it is there.
It changes what the control announces and nothing else. The control stays in the tab order, stays readable, and still fires whatever handlers you left on it. Turning the behaviour off is your code's job. This attribute only reports that you did.
Which roles may carry aria-disabled
- Value
- true/false
- Filed as
- A state, which is how ARIA files it and not a rule about how often it changes.
- Roles that may carry it
application,button,composite,gridcell,group,input,link,menuitem,scrollbar,separator,tab- Roles that inherit it
checkbox,columnheader,combobox,grid,listbox,menu,menubar,menuitemcheckbox,menuitemradio,option,radio,radiogroup,row,rowheader,searchbox,select,slider,spinbutton,switch,tablist,textbox,toolbar,tree,treegrid,treeitem
Those lists are not advice. Browsers are required to ignore a non-global attribute sitting on a role that does not support it, so aria-disabled on the wrong element is not weak, it is absent. You can read it in the DOM and nobody using a screen reader can.
Every role above comes from the specification's own list for this attribute, checked name for name. The normative definition stays with the W3C, in the aria-disabled section of the ARIA specification.
Keeping aria-disabled true
That gap between what the attribute says and what the control does is the whole risk. A button marked disabled here and still wired up will run when somebody presses Enter on it, and the person who pressed it had just been told it was unavailable. So the pair moves together, both when you disable and when you enable again. The spec also draws a line about where to use it. On a link it works well, because HTML cannot disable a link at all. On a control the host language can disable properly, authors are advised to use the host language and leave this alone. One more thing if you meet it in older code. It used to be allowed on any role, ARIA 1.2 deprecated that global use, and future versions will only allow it where a role supports it.
How aria-disabled gets checked
There are test rules that check an ARIA attribute is one that exists, is allowed on the role underneath it, and carries a value of the right type. What they map to is ARIA's own author requirements rather than any WCAG criterion, so a misplaced attribute breaks ARIA without being a WCAG failure by itself. It becomes one under 4.1.2 Name, Role, Value the moment the missing or wrong value means the control's state cannot be worked out programmatically, which is what usually happens next.
Nothing automated catches the failure this page is about. A stale value is a valid value, on a permitted role, with the right type. It is only wrong about the world.
Attributes you will meet alongside aria-disabled
- aria-activedescendant Points at the item inside a composite widget that is currently active, when focus stays on the container.
- aria-errormessage Points at the message explaining why this field is invalid. Only meaningful while aria-invalid is set.
- aria-expanded Whether the thing this control opens is currently open.
- aria-haspopup Says this control opens something, and what kind of thing it opens. A menu, a dialog, a listbox.
- aria-invalid Says a field's value has failed validation.
- aria-orientation Whether a widget runs horizontally or vertically, which decides which arrow keys move through it.
- aria-posinset Which position this item holds in its set, when the markup does not contain the whole set.
- aria-pressed Whether a toggle button is currently pressed. This is what makes a button a toggle.
Every ARIA state and property · Every ARIA role · ARIA explained