This specification defines the values for the
KeyboardEvent.key
attribute, which is defined as part of the
Document Object Model (DOM) Level 3 Events Specification [DOM3 Events].
The key
attribute contains information about the character
generated by the key event.
This document is a Working Draft of the
DOM Level 3 KeyboardEvent key
Values
specification.
It is expected that this specification will progress to
W3C
Recommendation status after review and refinement.
This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and MAY be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
You can find the latest Editor's Draft of this document in the W3C's Mercurial repository, which is updated on a regular basis.
Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.
key
Value TablesThis section defines a list of key
values which implementations MUST support, at a minimum, in addition to support for the full range of Unicode [Unicode]
codepoints.
The KeyboardEvent.key
attribute of an event MUST always contain one of these control key
or character values (even if the value is 'Unidentified'
). If the key represents one of the set of printable
control characters which has a Unicode character entry, such as the tab key, the KeyboardEvent.key
attribute
MUST have the key value (e.g., 'Tab'
).
Implementations that are unable to identify a key MUST use the key value 'Unidentified'
.
Warning! Conforming implementations MUST only use 'Unidentified'
as a key value when there is no way for the implementation to detect the key value.
Exposing only this value MUST NOT indicate a conforming implementation.
The key values defined in this specification are based in part on the sets of keycodes from
the java.awt.event.KeyEvent
interface of the Java Platform, Standard Edition 6 API Specification
[KeyEvent for Java],
and the System.Windows.Forms.Keys
key enumeration of the Microsoft .NET Framework 4.0 Class Library
[Keys enumeration for .Net].
Note: The keys on the numeric keypad (e.g., the keypad '1'
key) do not generate distinct key
values
from their non-keypad counterparts (e.g., the '1'
key in the main part of the keyboard).
The KeyboardEvent.location
attribute can be used to determine if a key originated from the numeric keypad.
Note: There are special internationalization considerations for ECMAScript escaped characters. CharMod conformance [CharMod] expects the use of code points rather than surrogate pairs in escapes.
ECMAScript escaped characters use surrogate pairs for characters outside the Basic Multilingual Plane ("\uD84E\uDDC2"
for '𣧂'
,
a Chinese character meaning untidy
), rather than C-style fixed-length characters ("\U000239c2"
for '𣧂'
) or delimited escapes
such as Numeric Character References ("𣧂"
). Characters escaped in this manner:
The following sub-sections contain the normative list of case-sensitive key values, their character values (where applicable), an informative description of typical usage,
and an informative categorization. A conforming implementation of the KeyboardEvent interface MUST support at least this set
of values for use in the KeyboardEvent.key
attributes, though not all values MAY be available on all platforms or devices.
Future versions of this specification MAY include key values not included here, which have become common since the publication of this specification.
KeyboardEvent.getModifierState()
method. This virtual key is always set in conjunction with one of the other modifier keys in this list.
For Windows, this virtual key is equivalent to the 'Control'
key.
For Mac OS, this key is typically equivalent to the 'Meta'
key.
Although note that the 'Meta'
key on other platforms is not necessarily associated
with the 'Accel'
.
'Option'
key.
'Shift'
key is the level 2 modifier).
'Command'
('⌘'
) key.
Windows Logokey).
'Return'
(Macintosh numpad) key.
Note: The space or spacebar key is encoded as ' '
.
'delete'
on MacOS keyboards.
'delete'
on MacOS keyboards when modified by the 'Fn'
key.
'OS'
key and the right 'Control'
key.
Note: Do not use this value for the pause button on media controllers. Use 'MediaPause'
instead.
Note: Do not use this value for the play button on media controllers. Use 'MediaPlay'
instead.
Note: Some devices might not expose this key to the operating environment.
'\u0302'
COMBINING CIRCUMFLEX ACCENT. In another layout this might be a different unicode combining key.
For applications that need to differentiate between specific combining characters, the associated compositionupdate
event's data attribute provides the specific key value.Keys specific to Korean keyboards
Keys specific to Japanese keyboards
The exact number of these general purpose function keys varies on different platforms, and only the first few are defined explicitly here. Additional function key names are implicitly defined by incrementing the base-10 index at the end of the function key name. Thus, 'F24' and 'Soft8' are all valid key values.
These are extra keys found on "multimedia" keyboards.
The Application Keys are special keys that are assigned to launch a particular application. Additional application key names can be defined by concatenating 'Launch' with the name of the application.
The key values for media controllers (e.g. remote controls for television, audio systems, and set-top boxes) are derived in part from the consumer electronics technical specifications:
Note: Do not confuse this key value with the Windows' VK_APPS / VK_CONTEXT_MENU key, which is encoded as 'ContextMenu'
.
Note: Media controller devices should use this value rather than 'Pause'
for their pause keys.
Some of the keys defined in the media controller standards already have appropriate keys defined in other sections of this specification. These following table summarizes the key values that MUST be used:
Over the years, many people contributed to the DOM KeyboardEvent specifications,
including many participants of the DOM Working Group and the WebApps Working Group.
The current set of key
values is the result of iterating over many proposals
and variations during that time.
We especially thank the following participants for their contributions:
Gary Kacmarcik (Google), Masayuki Nakano (Mozilla) and Travis Leithead (Microsoft).
For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR/.