WAI-ARIA: aria-keyshortcuts (Property)

Description

New in ARIA 1.1

Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.

The value of the aria-keyshortcuts attribute is a space-delimited list of keyboard shortcuts that can be pressed to activate a command or textbox widget. The keys defined in the shortcuts represent the physical keys pressed and not the actual characters generated. Each keyboard shortcut consists of one or more tokens delimited by the plus sign (“+”) representing zero or more modifier keys and exactly one non-modifier key that must be pressed simultaneously to activate the given shortcut.

Authors MUST specify modifier keys exactly according to the UI Events KeyboardEvent key Values spec [uievents-key] – for example, “Alt”, “Control”, “Shift”, “Meta”, or “AltGraph”. Note that Meta corresponds to the Command key, and Alt to the Option key, on Apple computers.

The valid names for non-modifier keys are any printable character such as “A”, “B”, “1”, “2”, “$”, “Plus” for a plus sign, “Space” for the spacebar, or the names of any other non-modifier key specified in the UI Events KeyboardEvent key Values spec [uievents-key] – for example, “Enter”, “Tab”, “ArrowRight”, “PageDown”, “Escape”, or “F1”. The use of “Space” for the spacebar is an exception to the UI Events KeyboardEvent key Values spec [uievents-key] as the space or spacebar key is encoded as ‘ ‘ and would be treated as a whitespace character.

Authors MUST ensure modifier keys come first when they are part of a keyboard shortcut. Authors MUST ensure that required non-modifier keys come last when they are part of a shortcut. The order of the modifier keys is not otherwise significant, so “Alt+Shift+T” and “Shift+Alt+T” are equivalent, but “T+Shift+Alt” is not valid because all of the modifier keys don’t come first, and “Alt” is not valid because it doesn’t include at least one non-modifier key.

When specifying an alphabetic key, both the uppercase and lowercase variants are considered equivalent: “a” and “A” are the same.

When implementing keyboard shortcuts authors should consider the keyboards they intend to support to avoid unintended results. Keyboard designs vary significantly based on the device used and the languages supported. For example, many modifier keys are used in conjunction with other keys to create common punctuation symbols, create number characters, swap keyboard sides on bilingual keyboards to switch languages, and perform a number of other functions.

For many supported keyboards, authors can prevent conflicts by avoiding keys other than ASCII letters, as number characters and common punctuation often require modifiers. Here, the keyboard shortcut entered does not equate to the key generated. For example, in French keyboard layouts, the number of characters are not available until you press the Control key, so a keyboard shortcut defined as “Control+2” would be ambiguous as this is how one would type the “2” character on a French keyboard.

If the character used is determined by a modifier key, the author MUST specify the actual key used to generate the character, that is generated by the key, and not the resulting character. This convention enables the assistive technology to accurately convey what keys must be used to generate the shortcut. For example, on most U.S. English keyboards, the percent sign “%” can be input by pressing Shift+5. The correct way to specify this shortcut is “Shift+5”. It is incorrect to specify “%” or “Shift+%”. However, note that on some international keyboards the percent sign may be an unmodified key, in which case “%” and “Shift+%” could be correct on those keyboards.

If the key that needs to be specified is illegal in the host language or would cause a string to be terminated, authors MUST use the string escaping sequence of the host language to specify it. For example, the double-quote character can be encoded as “Shift+'” in HTML.

Examples of valid keyboard shortcuts include:

“A”
“Shift+Space”
“Control+Alt+.”
“Control+Shift+'”
“Alt+Shift+P Control+F”
“Meta+C Meta+Shift+C”
User agents MUST NOT change keyboard behavior in response to the aria-key shortcuts attribute. Authors MUST handle scripted keyboard events to process aria-key shortcuts. The aria-key shortcuts attribute exposes the existence of these shortcuts so that assistive technologies can communicate this information to users.

Authors SHOULD provide a way to expose keyboard shortcuts so that all users may discover them, such as through the use of a tooltip. Authors MUST ensure that aria-key shortcuts applied to disabled elements are unavailable.

Authors SHOULD avoid implementing shortcut keys that inhibit operating system, user agent, or assistive technology functionality. This requires the author to carefully consider both which keys to assign and the contexts and conditions in which the keys are available to the user.

Browser Compatibility

Example

HTML Example

<p><a aria-keyshortcuts="alt+ctrl+m" href="#main">Skip to the main content</a></p>

HTML Example 2

<p><button id="ex1-delete" class="toolbar-item move-right-btn" tabindex="-1" aria-keyshortcuts="Alt+ArrowRight Delete" aria-disabled="true"><br>Not Important<br></button></p>

HTML Example 3

<a href="#content" aria-keyshortcuts="Alt+Shift+A">Skip to content</a>

Characteristics

Related Concepts

Keyboard shortcut

Used in Roles

All elements of the base markup

Value

String
Unconstrained value type.

Semantic HTML

No HTML element equivalent.

The aria-keyshortcuts attribute was added to convey which hotkey combinations are available to activate or focus on a particular element.

This is not like the accesskey attribute, where the modifier is handled by the browser and may differ between browsers, but instead represents the static shortcut combination that is programmed across all browsers.

In all cases where aria-keyshortcuts is used, these key commands need to be added by the developer using JavaScript, because there is no way for the browser or AT to know the expected functionality of all custom hotkey combinations. This attribute simply conveys the availability of these shortcuts and identifies what they are.

In short, adding the aria-keyshortcuts attribute without including the relevant scripting to make it work will result in shortcuts being conveyed to the user that do nothing when pressed.

At present, the aria-keyshortcuts attribute should only be used on focusable active elements.

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-keyshortcuts.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-keyshortcuts.