.keypress()

.keypress( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.

  • version added: 1.0.keypress( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.keypress()

This method is a shortcut for .bind('keypress', handler) in the first variation, and .trigger('keypress') in the second.

The keypress event is sent to an element when the browser registers keyboard input. This is similar to the keydown event, except in the case of key repeats. If the user presses and holds a key, a keydown event is triggered once, but separate keypress events are triggered for each inserted character. In addition, modifier keys (such as Shift) cause keydown events but not keypress events.

A keypress event handler can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
	<fieldset>
  	<input id="target" type="text" value="Hello there" />
	</fieldset>
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

$('#target').keypress(function() {
  alert('Handler for .keypress() called.');
});

Now when the insertion point is inside the field and a key is pressed, the alert is displayed:

Handler for .keypress() called.

The message repeats if the key is held down. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').keypress();
});

After this code executes, clicks on Trigger the handler will also alert the message.

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which character was entered, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the .which attribute so we can reliably use it to retrieve the character code.

Note that keydown and keyup provide a code indicating which key is pressed, while keypress indicates which character was entered. For example, a lowercase "a" will be reported as 65 by keydown and keyup, but as 97 by keypress. An uppercase "A" is reported as 65 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, .keydown() or .keyup() is a better choice.

Example:

Show the event object for the keypress handler when a key is pressed in the input.

<!DOCTYPE html>
<html>
<head>
  <style>
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
  width: 100%;
}
.print-output-line {
  white-space: pre;
  padding: 5px;
  font-family: monaco, monospace;
  font-size: .7em;
}

</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<form>
  <fieldset>
    <label for="target">Type Something:</label>
    <input id="target" type="text" />
  </fieldset>
</form>
<button id="other">
  Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>
<script>
var xTriggered = 0;
$('#target').keypress(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keypress() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keypress();
});</script>
</body>
</html>

Demo: