@npm-polymer/iron-a11y-keys v2.0.0

Demo and API docs

<iron-a11y-keys>

iron-a11y-keys provides a cross-browser interface for processing keyboard commands. The interface adheres to WAI-ARIA best practices. It uses an expressive syntax to filter key presses.

Basic usage

The sample code below is a portion of a custom element. The goal is to call the onEnter method whenever the paper-input element is in focus and the Enter key is pressed.

<iron-a11y-keys id="a11y" target="[[target]]" keys="enter"
                    on-keys-pressed="onEnter"></iron-a11y-keys>
<paper-input id="input"
             placeholder="Type something. Press enter. Check console."
             value="{{userInput::input}}"></paper-input>

The custom element declares an iron-a11y-keys element that is bound to a property called target. The target property needs to evaluate to the paper-input node. iron-a11y-keys registers an event handler for the target node using Polymer's annotated event handler syntax. {{userInput::input}} sets the userInput property to the user's input on each keystroke.

The last step is to link the two elements within the custom element's registration.

...
properties: {
  userInput: {
    type: String,
    notify: true,
  },
  target: {
    type: Object
  },
},
ready: function() {
  this.target = this.$.input;
},
onEnter: function() {
  console.log(this.userInput);
}
...

The keys attribute

The keys attribute expresses what combination of keys triggers the event.

The attribute accepts a space-separated, plus-sign-concatenated set of modifier keys and some common keyboard keys.

The common keys are: a-z, 0-9 (top row and number pad), * (shift 8 and number pad), F1-F12, Page Up, Page Down, Left Arrow, Right Arrow, Down Arrow, Up Arrow, Home, End, Escape, Space, Tab, Enter.

The modifier keys are: Shift, Control, Alt, Meta.

All keys are expected to be lowercase and shortened. E.g. Left Arrow is left, Page Down is pagedown, Control is ctrl, F1 is f1, Escape is esc, etc.

Grammar

Below is the EBNF Grammar of the keys attribute.

modifier = "shift" | "ctrl" | "alt" | "meta";
ascii = ? /[a-z0-9]/ ? ;
fnkey = ? f1 through f12 ? ;
arrow = "up" | "down" | "left" | "right" ;
key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" |
      "home" | "end" | arrow | ascii | fnkey;
event = "keypress" | "keydown" | "keyup";
keycombo = { modifier, "+" }, key, [ ":", event ] ;
keys = keycombo, { " ", keycombo } ;

Example

Given the following value for keys:

ctrl+shift+f7 up pagedown esc space alt+m

The event is fired if any of the following key combinations are fired: Control and Shift and F7 keys, Up Arrow key, Page Down key, Escape key, Space key, Alt and M keys.

WAI-ARIA Slider Example

The following is an example of the set of keys that fulfills WAI-ARIA's "slider" role best practices:

<iron-a11y-keys target="[[target]]" keys="left pagedown down"
                on-keys-pressed="decrement"></iron-a11y-keys>
<iron-a11y-keys target="[[target]]" keys="right pageup up"
                on-keys-pressed="increment"></iron-a11y-keys>
<iron-a11y-keys target="[[target]]" keys="home"
                on-keys-pressed="setMin"></iron-a11y-keys>
<iron-a11y-keys target=""[[target]] keys="end"
                on-keys-pressed="setMax"></iron-a11y-keys>

The target properties must evaluate to a node. See the basic usage example above.

Each of the values for the on-keys-pressed attributes must evalute to methods. The increment method should move the slider a set amount toward the maximum value. decrement should move the slider a set amount toward the minimum value. setMin should move the slider to the minimum value. setMax should move the slider to the maximum value.