# ally.element.disabled

Makes an element inert, i.e. not editable.

# Description

HTML knows the :disabled state for form elements, but lacks something similar for all the other interactive elements. This utility makes a form of this convenient state available to every element.

Elements that were made inert by ally.element.disabled can be identified in the DOM by the attribute [data-ally-disabled="true"] to align with styling of other :disabled elements.

The following things are done in order to make an element inert:

adding tabindex="-1" attribute to remove element from document's focus navigation sequence
adding the focusable="false" attribute on SVGElement
removing the controls attribute from <audio> and <video> elements
overwriting element.focus() to prevent focusing the element by script
adding the CSS property pointer-events: none; to prevent any interaction from mouse and touch
adding aria-disabled="true" to inform the AccessibilityTree of the element's state

The WICG (Web Incubater Community Group) is working on reviving the inert attribute (including a polyfill).

# Usage

var element = document.getElementById('victim');
// disable the element
ally.element.disabled(element, true);
// enable the element
ally.element.disabled(element, false);
// check the elements disabled state
var isDisabled = ally.element.disabled(element);

# Arguments

Name	Type	Default	Description
element	`<selector>`	required	The Element to modify. First element of the collections is used.
state	boolean, `undefined`	`undefined`	`true` to disable the element, `false` to enable the element.

# Returns

HTMLElement if the state argument is a boolean.
Boolean if the state argument is undefined, being true if the element is disabled, false if not.

# Throws

TypeError if element argument does not resolve to an HTMLElement.

# Examples

# ally.element.disabled Example

ally.element.disabled Example on jsbin.com

play with ally.element.disabled Example on jsbin.com or open the document of ally.element.disabled Example

# Changes

As of v1.3.0 <a xlink:href="…"> is demoted to <a> in order to remove the element from the document's tabbing order in Firefox.

# Notes

Internet Explorer 10 - 11 leave a few disabled elements focusable and thus editable to the mouse, but not keyboard focusable Trident 962368, Trident 817488 (ally.js does not fix that). One can prevent this wrong behavior by adding :disabled { pointer-events: none; }.

In Blink and WebKit based browsers (Chrome, Opera, Safari, …) the <use> element is keyboard focusable if the content it references contains focusable elements. In Blink even <use tabindex="-1"> remains keyboard focusable. ally.js does not identify these <use> elements and can therefore not disable them. Blink 665121

In Google Chrome <audio controls> and <video controls> elements are made inert by removing the controls attribute - Blink 512133.

ally.is.disabled is able to identify elements disabled by ally.element.disabled
ally.maintain.disabled is a service finding focusable elements and disabling them within the DOM
HTML5: Disabled Elements
WICG: Adding a [disabled] attribute to <a>s