disabled.md

layout	tags
doc-api.html	argument-list, svg

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

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

• EXAMPLE: ally.element.disabled Example

Changes

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

Notes

• WARNING: 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; }.
• NOTE: In Google Chrome <audio controls> and <video controls> elements are made inert by removing the controls attribute - Blink 512133

Related resources

• 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

Contributing

• module source
• document source
• unit test
• functional test