path: root/files/es/web/api/keyboardevent/key/index.html

---
title: KeyboardEvent.key
slug: Web/API/KeyboardEvent/key
translation_of: Web/API/KeyboardEvent/key
---
<p>{{APIRef("DOM Events")}}</p>

<p><span class="seoSummary">La propiedad de solo lectura<strong> </strong><code><strong>KeyboardEvent.key</strong></code> retorna el valor de la tecla presionada por el usuario while taking into considerations the state of modifier keys such as the <code>shiftKey</code> as well as the keyboard locale/layout.</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>Si la tecla presionada tiene una representación impresa, el valor devuelto es una cadena de caracteres Unicode no-vacía que contiene la representación imprimible de la tecla.</li>
 <li>Si la tecla presionada es un control o un carácter especial, el valor devuelto es uno de los <a href="/docs/Web/API/KeyboardEvent/key/Key_Values">valores clave definidos</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>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>

<h2 id="KeyboardEvent_Sequence">KeyboardEvent Sequence</h2>

<p><code>KeyboardEvent</code>s are fired in a pre-determined sequence and understanding this will go a long way into understanding the <code>key</code> property value for a particular <code>KeyboardEvent</code>. For a given key press, the sequence of <code>KeyboardEvent</code>s fired is as follows assuming that {{domxref("Event.preventDefault")}} is not called:</p>

<ol>
 <li>A {{event("keydown")}} event is first fired. If the key is held down further and the key produces a character key, then the event continues to be emitted in a platform implementation dependent interval and the {{domxref("KeyboardEvent.repeat")}} read only property  is set to <code>true</code>.</li>
 <li>If the key produces a character key that would result in a character being inserted into possibly an {{HTMLElement("input")}}, {{HTMLElement("textarea")}} or an element with {{domxref("HTMLElement.contentEditable")}} set to true, the {{event("beforeinput")}} and {{event("input")}} event types are fired in that order. Note that some other implementations may fire {{event("keypress")}} event if supported. The events will be fired repeatedly while the key is held down.</li>
 <li>A {{event("keyup")}} event is fired once the key is released. This completes the process.</li>
</ol>

<p>In sequence 1 &amp; 3, the <code>KeyboardEvent.key</code> attribute is defined and is set appropriately to a value according to the rules defined ealier.</p>

<h2 id="KeyboardEvent_Sequence_Sample">KeyboardEvent Sequence Sample</h2>

<p>Consider the event sequence generated when we interact with the <code>ShiftKey</code> and the legend <code>key 2</code> using a U.S keyboard layout and a UK keyboard layout.</p>

<p>Try experimenting using the following two test cases:</p>

<ol>
 <li>Press and hold the <code>shift</code> key, then press <code>key 2</code> and release it. Next, release the <code>shift</code> key.</li>
 <li>Press and hold the <code>shift</code> key, then press and hold <code>key 2</code>. Release the <code>shift</code> key. Finally, release <code>key 2</code>.</li>
</ol>

<h3 id="HTML">HTML</h3>

<pre class="brush: html">&lt;div class="fx"&gt;
  &lt;div&gt;
    &lt;textarea rows="5" name="test-target" id="test-target"&gt;&lt;/textarea&gt;
    &lt;button type="button" name="btn-clear-console" id="btn-clear-console"&gt;clear console&lt;/button&gt;
  &lt;/div&gt;
  &lt;div class="flex"&gt;
    &lt;div id="console-log"&gt;&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;
</pre>

<h3 id="CSS">CSS</h3>

<pre class="brush: css">.fx {
  -webkit-display: flex;
  display: flex;
  margin-left: -20px;
  margin-right: -20px;
}

.fx &gt; div {
  padding-left: 20px;
  padding-right: 20px;
}

.fx &gt; div:first-child {
   width: 30%;
}

.flex {
  -webkit-flex: 1;
  flex: 1;
}

#test-target {
  display: block;
  width: 100%;
  margin-bottom: 10px;
}</pre>

<h3 id="JavaScript">JavaScript</h3>

<pre class="brush: js">let textarea = document.getElementById('test-target'),
consoleLog = document.getElementById('console-log'),
btnClearConsole = document.getElementById('btn-clear-console');

function logMessage(message) {
  let p = document.createElement('p');
  p.appendChild(document.createTextNode(message));
  consoleLog.appendChild(p);
}

textarea.addEventListener('keydown', (e) =&gt; {
  if (!e.repeat)
    logMessage(`first keydown event. key property value is "${e.key}"`);
  else
    logMessage(`keydown event repeats. key property value is "${e.key}"`);
});

textarea.addEventListener('beforeinput', (e) =&gt; {
  logMessage(`beforeinput event. you are about inputing "${e.data}"`);
});

textarea.addEventListener('input', (e) =&gt; {
  logMessage(`input event. you have just inputed "${e.data}"`);
});

textarea.addEventListener('keyup', (e) =&gt; {
  logMessage(`keyup event. key property value is "${e.key}"`);
});

btnClearConsole.addEventListener('click', (e) =&gt; {
  let child = consoleLog.firstChild;
  while (child) {
   consoleLog.removeChild(child);
   child = consoleLog.firstChild;
  }
});</pre>

<h3 id="Result">Result</h3>

<p>{{EmbedLiveSample('KeyboardEvent_Sequence_Sample')}}</p>

<h3 id="Case_1">Case 1</h3>

<p>When the shift key is pressed, a {{event("keydown")}} event is first fired, and the <code>key</code> property value is set to the string <code>"Shift"</code>. As we keep holding this key, the {{event("keydown")}} event does not continue to fire repeatedly because it does not produce a character key.</p>

<p>When <code>key 2</code> is pressed, another {{event("keydown")}} event is fired for this new key press, and the <code>key</code> property value for the event is set to the string <code>"@"</code> for the U.S keyboard type and <code>"""</code> for the UK keyboard type, because of the active modifier <code>shift</code> key. The {{event("beforeinput")}} and {{event("input")}} events are fired next because a character key has been produced.</p>

<p>As we release the <code>key 2</code>, a {{event("keyup")}} event is fired and the <code>key</code> property will maintain the string values <code>"@"</code> and <code>"""</code> for the different keyboard layouts respectively.</p>

<p>As we finally release the <code>shift</code> key, another {{event("keyup")}} event is fired for it, and the key attribute value remains <code>"Shift"</code>.</p>

<h3 id="Case_2">Case 2</h3>

<p>When the shift key is pressed, a {{event("keydown")}} event is first fired, and the <code>key</code> property value is set to be the string <code>"Shift"</code>. As we keep holding this key, the keydown event does not continue to fire repeatedly because it produced no character key.</p>

<p>When <code>key 2</code> is pressed, another {{event("keydown")}} event is fired for this new key press, and the <code>key</code> property value for the event is set to be the string <code>"@"</code> for the U.S keyboard type and <code>"""</code> for the UK keyboard type, because of the active modifier <code>shift</code> key. The {{event("beforeinput")}} and {{event("input")}} events are fired next because a character key has been produced. As we keep holding the key, the {{event("keydown")}} event continues to fire repeatedly and the {{domxref("KeyboardEvent.repeat")}}  property is set to <code>true</code>. The {{event("beforeinput")}} and {{event("input")}} events are fired repeatedly as well.</p>

<p>As we release the <code>shift</code> key, a {{event("keyup")}} event is fired for it, and the key attribute value remains <code>"Shift"</code>. At this point, notice that the <code>key</code> property value for the repeating keydown event of the <code>key 2</code> key press is now "2" because the modifier <code>shift</code> key is no longer active. The same goes for the {{domxref("InputEvent.data")}} property of the {{event("beforeinput")}} and {{event("input")}} events.</p>

<p>As we finally release the <code>key 2</code>, a {{event("keyup")}} event is fired but the <code>key</code> property will be set to the string value <code>"2"</code> for both keyboard layouts because the modifier <code>shift</code> key is no longer active.</p>

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

<p>This example uses {{domxref("EventTarget.addEventListener()")}} to listen for {{event("keydown")}} events. When they occur,  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; // Do nothing if the event was already processed
  }

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

  // Cancel the default action 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>{{Compat("api.KeyboardEvent.key")}}</p>