Revision 1109735 of KeyboardEvent.key

<p>{{APIRef("DOM Events")}}{{Draft}}</p>

<p><span class="seoSummary">The <code><strong>KeyboardEvent.key</strong></code> read-only property returns the value of a key or keys pressed by the user.</span> Its value is determined as follows:</p>

<div class="pull-aside">
<p class="moreinfo">See a full list of <a href="/docs/Web/API/KeyboardEvent/key/Key_Values">key values</a>.</p>
</div>

<ul>
 <li>If the pressed key has a printed representation, the returned value is a non-empty Unicode character string containing the printable representation of the key.</li>
 <li>If the pressed key is a control or special character, the returned value is one of the <a href="/docs/Web/API/KeyboardEvent/key/Key_Values">pre-defined key values</a>.</li>
 <li>If the <code>KeyboardEvent</code> represents the press of a dead key, the key value must be "<code>Dead</code>".</li>
 <li>If more than one key is pressed and the combination includes a modifier that makes the resulting keystroke non printing, the returned value is the printable character. For example, if the combination were Control + a, the letter "a" is returned.</li>
 <li>Some specialty keyboard keys (such as the extended keys for controlling media on multimedia keyboards) don't generate key codes on Windows; instead, they trigger <code>WM_APPCOMMAND</code> events. These events get mapped to DOM keyboard events, and are listed among the "Virtual key codes" for Windows, even though they aren't actually key codes.</li>
 <li>If the key cannot be identified, the returned value is <code>"Unidentified"</code>.</li>
</ul>

<div class="note">
<p>This page is undergoing heavy updating to improve its layout, modernize its content, and bring everything up to date. Newer content is nearer the top; to find the older tables, see {{anch("Previous versions of tables")}}. Once the updates are finished, that content will be removed. No information should be lost once it's all done.</p>
</div>

<h2 id="Example">Example</h2>

<p>This example uses {{domxref("EventTarget.addEventListener()")}} to listen for {{event("keydown")}} events. When they occur,&nbsp; the key's value is checked to see if it's one of the keys the code is interested in, and if it is, it gets processed in some way (possibly by steering a spacecraft, perhaps by changing the selected cell in a spreadsheet).</p>

<pre class="brush: js">
window.addEventListener("keydown", function (event) {
  if (event.defaultPrevented) {
    return; // Should do nothing if the key event was already consumed.
  }

  switch (event.key) {
    case "ArrowDown":
      // Do something for "down arrow" key press.
      break;
    case "ArrowUp":
      // Do something for "up arrow" key press.
      break;
    case "ArrowLeft":
      // Do something for "left arrow" key press.
      break;
    case "ArrowRight":
      // Do something for "right arrow" key press.
      break;
    case "Enter":
      // Do something for "enter" or "return" key press.
      break;
    case "<code>Escape</code>":
      // Do something for "esc" key press.
      break;
    default:
      return; // Quit when this doesn't handle the key event.
  }

  // Consume the event to avoid it being handled twice
  event.preventDefault();
}, true);
</pre>

<h2 id="Specification">Specification</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM3 Events', '#widl-KeyboardEvent-key', 'KeyboardEvent.key')}}</td>
   <td>{{Spec2('DOM3 Events')}}</td>
   <td>Initial definition, included key values.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>
    <p>{{CompatChrome(51.0)}}</p>
   </td>
   <td>{{CompatGeckoDesktop("23.0")}}</td>
   <td>9.0[1]</td>
   <td>38.0</td>
   <td>{{CompatNo}} [2]</td>
  </tr>
  <tr>
   <td>non-printable keys</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoDesktop("23.0")}}</td>
   <td>9.0[1]</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td>printable keys</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoDesktop("29.0")}}</td>
   <td>9.0[1]</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td>dead key</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">s
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE&nbsp;Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoMobile("23.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>38.0</td>
   <td>{{CompatNo}} [2]</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
  <tr>
   <td>non-printable keys of virtual keyboard</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoMobile("23.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
  <tr>
   <td>printable keys of virtual keyboard</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
  <tr>
   <td>non-printable keys of physical keyboard</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoMobile("23.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
  <tr>
   <td>printable keys of physical keyboard</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatGeckoMobile("29.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>38.0</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1]: Internet Explorer's implementation does not completely match the current spec because it is based on an older version of the spec.</p>

<p>[2]: <a href="https://bugs.webkit.org/show_bug.cgi?id=69029">WebKit bug #69029</a></p>