UI Events KeyboardEvent code Values

1. Introduction

This document provides an overview of the various keyboard layouts and specifies the code values that should be used for each of the keys. Unlike the key values described in [UIEvents-key], the code values are based only on the key’s physical location on the keyboard and do not vary based on the user’s current locale.

This specification was formerly titled DOM Level 3 KeyboardEvent code Values.

1.1. Stylistic Conventions

This specification uses the following conventions:

• The key cap or label printed on a key is shown as ↓, = or Q. This is used to refer to a key from the user’s perspective without regard for the key and code values in the generated KeyboardEvent.

• Glyphs representing character are shown as: "𣧂".

• Unicode code points are shown as: U+003D.

• Valid key attribute values (i.e., the value of a key attribute) are shown as: "ArrowDown", "=", "q" or "Q".

• Valid key code attribute values (i.e., the value of a code attribute) are shown as: "ArrowDown", "Equal" or "KeyQ".

2. Keyboard Layout

This section is non-normative.

Alphanumeric keyboards are the most common way for users to generate keyboard events. This section provides an overview of standard keyboards and their physical layouts.

2.1. Standard Keyboard Layouts

This section describes the physical layouts found on commonly available keyboards.

2.1.1. Keyboard Sections

When discussing keyboard layouts, it is convenient to divide the standard keyboard into distinct sections and to label each row.

These keyboard sections are:

• The alphanumeric section is the main part of the keyboard and is where most of the keyboard variation occurs. When a user selects a keyboard layout, it is the keys in this sections that are most affected.

• The control pad and arrow pad sections contain the arrow keys and other editing keys.

• The numpad (also known as the "numeric keypad" or "number pad") contains number and math keys to make it easier to enter numeric data.

• And finally, the function section contains miscellaneous function keys and special keys like Escape.

To make it easier to identify keys, the rows on the keyboard are named starting with "A" for the bottom row up to "E" for the top row. The row of keys in the function section are considered to be in row "K". These row names are consistent with those given in [ISO9995-1].

Note that many keyboards (both modern and legacy) have extra keys that do not fit neatly into the above sections. Some of these keys are covered in § 3.6 Media Keys.

2.1.2. Standard "101" Keyboard Layout

The standard "101" keyboard (commonly referred to as the "US layout") is the only layout that has a "Backslash" key (labeled \|) above a single-row Enter key. All the other layouts omit this key and expand the Enter key to occupy two-rows.

Modern standard "101"-layout keyboards actually contain 104 keys: 61 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections. The "101" name for this keyboard layout dates to the time when this standard keyboard did in fact contain 101 keys. The two Meta keys (commonly given an OS-specific label), and the Menu key were added later to bring the total to 104 keys.

2.1.3. Alternate "101" Keyboard Layout

The alternate "101" keyboard has a large Enter key and shrinks the Backspace key to make room for the "IntlYen" key (which replaces the "Backslash" key found in the standard 101 layout). The "IntlYen" name comes from the Japanese layout where this is the ¥ (yen) key — in the Russian layout shown below this key maps to a \/.

Modern alternate "101"-layout keyboards contain 104 keys: 61 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.

2.1.4. Standard "102" Keyboard Layout

The standard "102" keyboard is common throughout Europe and adds a key that doesn’t exist on the "101" layouts: The "IntlBackslash" key (labelled \| on a UK keyboard) next to the left shift key.

A second key is also added (labelled #~ on a UK keyboard) which is partially tucked under the Enter key. This key is encoded as "Backslash", using the same code as the \| key found on the "101" keyboard layout. According to [USB-HID], the US \| and UK #~ are actually two separate keys (named "Keyboard \ and |" and "Keyboard Non-US # and ~"), but since these two keys never co-occur on the same keyboard most platforms use the same scancode for both keys, making them difficult to distinguish. It is for this reason that the code "Backslash" is used for both of these keys.

Modern "102"-layout keyboards contain 105 keys: 62 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.

2.1.5. Korean "103" Keyboard Layout

The Korean "103" keyboard is based on the alternate 101 layout and adds two additional keys (one on each side of the spacebar) to handle Korean-specific input modes. These keys are "Lang2" ("Hanja", labelled 한자 hanja) and "Lang1" ("HangulMode", labelled 한/영 han/yeong).

Modern "103"-layout keyboards contain 106 keys: 63 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.

2.1.6. Brazilian "104" Keyboard Layout

The "104" layout used in Brazil adds 4 new keys: two keys from the "102" layout ("Backslash" and "IntlBackslash") plus the "IntlRo" key (next to the right shift key) and an extra key on the numpad. This new numpad key is called "NumpadComma" because it represents the thousands separator. On the Brazilian key layout, this key is labelled . and the "NumpadDecimal" key is labelled ,.

Modern "104"-layout keyboards contain 107 keys: 63 keys in the alphanumeric section and 44 keys in the numpad, control pad, arrow pad and function sections. Some Brazilian keyboards lack the extra numpad key and have only 106 keys.

2.1.7. Japanese "106" Keyboard Layout

The Japanese "106" keyboard layout adds 3 new keys: "IntlYen" (labelled ¥_), "Backslash" (labelled ]む) and "IntlRo" (labelled \ろ). It also shrinks the spacebar to make room for 3 input mode keys: "NonConvert" (labelled 無変換 muhenkan), "Convert" (labelled 変換 henkan) and "KanaMode" (labelled カタカナ/ひらがな/ローマ字 katakana/hiragana/romaji).

Modern "106"-layout keyboards contain 109 keys: 66 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.

2.1.8. Apple Keyboard Layout

In general, Apple keyboards follow the same layout as PC keyboards, but there are some differences as noted in the following figure.

In this figure, the green keys are those that have been moved to a new location while the blue keys indicate keys that have been added.

2.1.9. Laptop Keyboard Layouts

The limited space available on laptop keyboards often means that the physical key layout needs to be adjusted to fit all the required keys. The writing system keys in the alphanumeric section tend to remain intact, but the other keyboard sections are usually combined with other keys or removed altogether.

In this Apple laptop keyboard, the right control key has been removed to make room for half-height arrow keys and a Fn key is added on the left.

PC laptop keyboards vary considerably, but this sample keyboard demonstrates some commonly found aspects. The control pad keys are added along the right-hand side with the arrow pad keys tucked in along the bottom. The right Shift key is often shrunk to make room for the up arrow key and the right Meta key is typically removed altogether.

2.1.10. Keyboard Layouts For Other Locales

Other locales are not explicitly described in this specification because they start with one of the existing layouts and adapt it by changing the keycaps and the key mappings.

Because these keyboards do not introduce new physical keys, they do not require explicit documentation.

These keyboards are typically based on the "101" (standard or alternate) or "102" layouts. For example, the common Arabic, Cyrillic, Greek, Hindi, Khmer and Thai keyboards are all based on either the "101" or "102" keyboard layouts.

2.2. Mobile Keypads

In the case where a content author wishes to rely on the mechanical layout of a mobile keypad, this specification suggests the keyboard configuration specified in [ISO9995-8], which defines a numeric keypad layout and secondary assignment of Unicode characters in the range U+0061 ... U+007A ("a" - "z") to the number keys 2 through 9, as a common layout appropriate to some international uses.

This keypad layout, and in particular the distribution of letters is for English devices, and will not match the keypads or configurations of many users. Content authors cannot rely upon any particular configuration, and are expected to create content in an internationalized and localizable manner.

2.3. Media Remote Controls

Many keyboards contain special keys to control media functions. Increasingly, many media devices, especially televisions, are Web-enabled. Hybrid keyboard/remote-control devices are becoming more common. To meet the needs of these hybrid Web/media devices, this specification defines keys that are common as remote control buttons, in addition to traditional keyboard keys.

Because of the smaller form factor, keys (or buttons) on a remote control will often be modal, with one key performing different functions based on the context of the on-screen content. Additionally, many keys serve as toggles, to change back and forth between two or more states (see toggling keys). These remote control buttons typically do not have modifier states so each button is assigned a single function (like Play, Pause, Up, Menu or Exit).

2.4. Virtual Keyboards and Chording Keyboards

Virtual keyboards are software-based sets of keys, in a variety of different arrangements, commonly found on touch-screen devices. They are often modal, with the ability to switch between different dynamic sets of keys, such as alphabetic, numeric, or symbolic keys. Because of the lack of physical constraints, these keyboards MAY present the widest range of characters, including emoticons and other symbols. Wherever possible, however, virtual keyboards SHOULD produce the normal range of keyboard events and values, for ease of authoring and compatibility with existing content.

Chording keyboards, also known as chorded keysets or chord keyboards, are key input devices which produce values by pressing several keys in combination or sequence, normally to simulate a full range of characters or commands on a reduced set of keys, often for single-handed use. A chording keyboard MAY have additional mode keys to switch between key values, and the number and type of keys pressed to produce a key value will vary, but the final key values produced by such keyboards SHOULD match the range of key values described in this specification.

For these and other alternative modal keyboards, the key values "Alphanumeric", "CapsLock", "NumLock", and "SymbolLock" are RECOMMENDED for the keys which switch between different modes.

3. Keyboard Event code Value Tables

This section defines a list of values which are appropriate for use as code values.

A key code attribute value is any of the values given in the "KeyboardEvent.code" column of any of the tables in this section of the specification.

Each table in this section has a "Required" column which indicates whether or not the value is required for a conforming implementation. Entries where the "Required" column is "No" are optional and may be used by implementations to support special keyboards (such as multimedia or legacy keyboards).

Note: Some values listed in this specification as "Required" may not be available on all platforms or devices. For example, Mac keyboards do not have an Insert key whereas standard PC keyboards do not have a Help key.

For every key listed as "Required" in this specification, a conforming implementation of the KeyboardEvent interface MUST return the correct value as long as that key is available on that platform.

Note: While every attempt has been made to make this list of values as complete as possible, new values will periodically need to be defined as new input devices are introduced. Rather than allowing user agents to define their own key code attribute values (which are unlikely to be consistent across multiple user agents), bugs SHOULD be filed so that this specification can be updated.

3.1. Alphanumeric Section

The alphanumeric section is the main section of the keyboard. It contains keys that fall into two general categories: writing system keys whose meaning changes based on the current keyboard layout, and functional keys which are (mostly) the same for all layouts.

3.1.1. Writing System Keys

The writing system keys are those that change meaning (i.e., they produce different key values) based on the current locale and keyboard layout.

This figure shows a hypothetical keyboard that combines all the writing system keys (shown in blue and green) found on the various keyboards. Blue keys are present on all standard keyboards while green keys are only available on some keyboards.

The name shown on each key is the code assigned to that key. Wherever possible, the code names are based on the name for the US key in that position (i.e., they are based on the US keyboard layout), which follows the naming convention found in [USB-HID]. For keys that don’t exist on the US keyboard, names from the UK or Japanese layouts are used instead.

Note that there are two "Backslash" keys in this figure: a large one at the end of Row D on the 101-key layout, and a smaller one between "Quote" and "Enter" on Row C of the 102-, 104- and 106-key layouts. Only one "Backslash" key may be present on a keyboard layout.