Special keyboard events

There are several special keyboard events to make it easier to handle keyboard navigation.

They have been given dedicated event names to save you the trouble of having to set up special conditionals or call external functions to handle them.

Essentially, the key value from the browser API for the key event is appended to the event string "keyup" or "keydown".

For example:

#myInputField:keyupEnter {
    alert: "You just hit the enter key.";
}

This functionality is very loosely coupled with the browser - it will try to run anything after "keyup" or "keydown" as a valid event, so be aware of this. It really depends on what the browser supports.

The key itself could be camel-case, or whatever the browser itself specifies for that key. The "keyup" and "keydown" words prefixing each key reference are always written in lowercase, as in the above example.

To find out the key string you want to trap, see this page:

https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key

Note that if you want to trap unusual characters then you might break your config syntax if you put them straight into your config, so if the key that you need is not in the list below then you might find you need to call an external function if you wish to trap these. If this happens, you can let us know the scenario so we can put it into the core if appropriate.

A list of common events follow below:

Additional keyup events

keyupArrowUp - traps the keyboard up arrow on a keyup event;
keyupArrowDown - traps the keyboard down arrow on a keyup event;
keyupArrowLeft - traps the keyboard left arrow on a keyup event;
keyupArrowRight - traps the keyboard right arrow on a keyup event;
keyupEnter - traps the enter key on a keyup event;
keyupEscape - traps the escape key on a keyup event.
keyupColon - traps the colon ":" key on a keyup event.
keyupSemicolon - traps the semi-colon ";" key on a keyup event.
keyupOpenCurly - traps the open curly bracket "{" key on a keyup event.
keyupCloseCurly - traps the close curly bracket "}" key on a keyup event.
keyupDoubleQuotes - traps the double-quotes (") key on a keyup event.
keyupSingleQuote - traps the single-quote (') key on a keyup event.
keyupQuestion - traps the question mark (?) key on a keyup event.
keyupExclamation - traps the exclamation point (!) key on a keyup event.
keyupSpace - traps the spacebar ( ) on a keyup event.
keyupa, keyupA, keyupb, etc.
keyup1, keyup2, etc.

Additional keydown events

keydownArrowUp - traps the keyboard up arrow on a keydown event;
keydownArrowDown - traps the keyboard down arrow on a keydown event;
keydownArrowLeft - traps the keyboard left arrow on a keydown event;
keydownArrowRight - traps the keyboard right arrow on a keydown event;
keydownEnter - traps the enter key on a keydown event;
keydownEscape - traps the escape key on a keydown event.
keydownColon - traps the colon ":" key on a keydown event.
keydownSemicolon - traps the semi-colon ";" key on a keydown event.
keydownOpenCurly - traps the open curly bracket "{" key on a keydown event.
keydownCloseCurly - traps the close curly bracket "}" key on a keydown event.
keydownDoubleQuotes - traps the double-quotes (") key on a keydown event.
keydownSingleQuote - traps the single-quote (') key on a keydown event.
keydownQuestion - traps the question mark (?) key on a keydown event.
keydownExclamation - traps the exclamation point (!) key on a keydown event.
keyupSpace - traps the spacebar ( ) on a keyup event.
keydowna, keydownA, keydownb, etc.
keydown1, keydown2, etc.

Ctrl, Meta, Shift special key combinations

To handle key combinations follow the following format in this exact order:

Eg. keyupCtrlSpace, keyupCtrlShiftA, etc.

Bear in mind that if you want to override a browser default shortcut key, you will need to include "prevent-default: true;" in your event code for your event to act as you intend. Please keep in mind accessibility considerations unless you know that your target audience doesn't practically need the default functionality that the shortcut key of the browser provides.

Syntax example

This syntax example is directly taken from this website to focus on the first search result when the down arrow is pressed in the search box and loop results with the down arrow key. It only fires if there are search results there and visible, and not if there is a "search not found" result - so there is a custom conditional declaration in there too.

If you are using the key events to change the focus of elements dynamically, remember to add :focus to your actual CSS in addition to the usual :hover CSS, so you can see the results and check if the item you want is being correctly focused. Some elements like being focused on, and some don't.

?populatedSearch {
    if-exists: #adm-SearchRes;
    if-display: #adm-SearchRes;
    !if-exists: .srch-NoResults;
}

#adm-Search:populatedSearch:keydownArrowDown, .srch-Res a:keydownArrowDown,
#adm-Search:populatedSearch:keydownArrowUp, .srch-Res a:keydownArrowUp {
    prevent-default: true;
}

#adm-Search:populatedSearch:keydownArrowDown {
    focus-on: .srch-Res a;
}

.srch-Res a:keyupEnter {
    trigger: click;
}

.srch-Res a:keydownArrowDown {
    focus-on-next-cycle: .srch-Res a;
}

.srch-Res a:not-if-focus-first(.srch-Res a):keydownArrowUp {
    focus-on-previous: .srch-Res a;
}

.srch-Res a:if-focus-first(.srch-Res a):keydownArrowUp {
    focus-on: #adm-Search;
}

Events: Custom events Events: The "clickoutside" event