aria-disabled

The aria-disabled state indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

Description

You generally want users to fill out all the required fields before submitting a form. One way to ensure all required fields are complete is to disable the submit button. However, you still want that submit button to be perceivable to all users. That is where the aria-disabled attribute comes in.

The aria-disabled attribute, when set to true, indicates to assistive technologies that the element upon which it is set and all focusable descendants are disabled. This declaration tells your user the elements are not editable or otherwise operable without making the element imperceivable.

There are several elements you may want to disable, but still want the user to know they exist. Some examples include:

  • Irrelevant options in a radio group,
  • The header button element associated with non-collapsible accordion panel,
  • A button when the action associated with the button is unavailable,
  • The icon for the currently visible slide in a slideshow slide picker, and
  • Items in a menu that are not currently selectable.

In each of these cases, you want the user to know the element is there even though the functionality of that control is removed or "disabled".

ARIA attributes only provide semantics. To semantically disable an element without removing it from focus order or from the accessibility tree, set aria-disabled="true" on the element. You should include JavaScript to disable the functionality of the element while also changing the appearance of the element so sighted users know it is disabled.

Note: The state of being disabled applies to the element with aria-disabled and all of its focusable descendants.

The aria-disabled attribute is similar to the HTML disabled attribute, but better. The first rule of ARIA is "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so." aria-disabled is an exception to that rule. It is one of the only cases where an ARIA attribute may be better than the native disabled attribute HTML equivalent.

The disabled Boolean attribute provides CSS styles and semantics and removes the ability to click or focus while not disabling hover. By removing the ability to focus and removing it from the accessibility tree, it makes it invisible to assistive technology users. For good user experience, you want to make sure everyone can access all the visible content, no matter how they access the web. It is important to be aware that using the disabled attribute can harm usability.

While adding disabled to an HTML form control causes :disabled user-agent styles to be applied, adding aria-disabled="true" doesn't, by default, alter an element's appearance. The element can be styled with the attribute selector `[aria-disabled="true"]

[aria-disabled="true"] {
  opacity: 0.5;
}

Note: If you are using CSS's pointer-events: none; to make an element non-clickable, make sure you disable interactivity with JavaScript as well. pointer-events: none; prevents mouse clicks, but does not prevent the element from being activated via the keyboard.

function onClick(event) {
  event.preventDefault();
}

function toggleDisabled(element, status, update) {
  if(status) {
    //element.input.disabled = false;
    element.setAttribute('aria-disabled', 'false');
    update.textContent = 'The element is now enabled.';
    element.removeEventListener('click', onClick);
  } else {
    //element.input.disabled = true;
    element.setAttribute('aria-disabled', 'true');
    update.textContent = 'The element is now disabled.';
    element.addEventListener('click', onClick);
  }
}

When toggling from aria-disabled="true" to "false", use JavaScript to:

  1. Toggle the value to false,
  2. Enable the element, and
  3. Let the user know the control is now enabled.

If you used just CSS to style the disabled state using an attribute selector, the selector will no longer match and the disabled styling will no longer be in effect.

Values

true

The element is disabled

false

The element is not disabled

ARIAMixin API

Element.ariaDisabled

The ariaDisabled property, part of the Element interface, reflects the value of the aria-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

ElementInternals.ariaDisabled

The ariaDisabled property of the ElementInternals interface reflects the value of the aria-disabled attribute.

Associated roles

Used in roles:

Inherits into roles:

Specifications

Specification Status
Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'ARIA: aria-disabled Attribute' in that specification.		 Recommendation

See Also