aria-disabled

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

Description

The aria-disabled attribute, when set to true, indicates that the element upon which it is set and all of its focusable descendants are meant to be in the disabled state. This declaration will inform people using assistive technologies, such as screen readers, that such elements are not meant to be editable or otherwise operable.

Unlike HTML's disabled Boolean attribute, which will communicate a form control as semantically being disabled, change its styling to reflect its state and suppress all functionality along with disallowing the element's value from participating in form submission, the aria-disabled="true" only semantically exposes these elements as being disabled. Web developers must manually ensure such elements have their functionality suppressed when exposed to the disabled state.

When needing to disable native HTML form controls, developers will need to specify the disabled attribute, as it provides all of the generally expected features of disabling a control by default. However, there can be instances where elements need to be exposed as disabled, but are still available for users to find when navigating via the Tab key. Doing so can improve their discoverability as they will not be removed from the focus order of the web page, as aria-disabled does not change the focusability of such elements, nor will the elements be dimmed by default browser styling, making them easier to read. Some examples of where this may be useful include:

  • The header button element associated with non-collapsible accordion panel,
  • A button which is important to keep in the page's focus order, but its action is presently unavailable - such as submitting a form,
  • Temporarily inactive items in a menu widget that would otherwise be skipped over via standard keyboard navigation.

In each of these cases, one may want users to find these elements through standard keyboard navigation, though the functionality of that control is removed or "disabled". Developers will still need to use JavaScript to fully 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="true" and all of its focusable descendants. Take care when using this attribute on container elements. Particularly in the case where a container may have both form controls and links - where the intent may be to expose the form controls as being in the disabled state, but not to communicate the links as being "disabled".

Another reason to need use the aria-disabled attribute over the HTML disabled attribute is if you have created custom controls which need to be marked as disabled, but are not using an element that allows for the disabled attribute. For instance, in the following snippet a <div> was used to create a custom button which needs to be marked as disabled. However, the <div> element does not expect, nor respect the disabled attribute - even if it were to be given a role="button" to change its exposed ARIA role. The aria-disabled attribute is required to disable such custom controls.

<div role="button" aria-disabled="true" tabindex="-1">Edit</div>

Similarly to needing to use JavaScript to ensure an element with aria-disabled="true" is not functional, the element will also need styling adjustments. In contrast to the HTML disabled attribute, where specifying it provides :disabled user-agent styles to be applied, adding aria-disabled="true" doesn't. The element can be styled with the attribute selector [aria-disabled="true"].

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

If you are purposefully using the aria-disabled attribute to allow for a form control to remain in the page's keyboard focus order, particularly if the element represents important content that all users should be able to perceive, then you may need to use styling that still passes color contrast requirements. For instance, a disabled button/heading that introduces a non-collapsible accordion panel is content that still needs to be legible.

@media (forced-colors: active) {
  [aria-disabled="true"] {
    border-color: GrayText;
    color: GrayText;
  }
}

The forced-colors media query detects if the user agent has enabled a forced colors mode; if so, the text and border colors are both set to the system color greyText.

Another thing to keep in mind, when using aria-disabled over the native HTML attribute, is that the ARIA attribute will require the manual styling necessary to visually communicate the element as disabled in Windows High Contrast Mode.

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.addEventListener("click", onClick);
  } else {
    //element.input.disabled = true;
    element.setAttribute("aria-disabled", "true");
    update.textContent = "The element is now disabled.";
    element.removeEventListener("click", onClick);
  }
}

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

  1. Toggle the value to false (or remove the attribute entirely),
  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
Accessible Rich Internet Applications (WAI-ARIA)
# aria-disabled

See Also