/jquery.hotkeys

jQuery Hotkeys lets you watch for keyboard events anywhere in your code supporting almost any key combination including the Mac cmd key. It also has support for key sequences.

Primary LanguageJavaScript

#About jQuery Hotkeys is a plug-in that lets you easily add and remove handlers for keyboard events anywhere in your code supporting almost any key combination.

This plugin is based off of the plugin by Tzury Bar Yochay: jQuery.hotkeys

The syntax is as follows:

$(expression).bind(types, keys, handler);
$(expression).unbind(types, handler);

$(document).bind('keydown', 'ctrl+a', fn);

// e.g. replace '$' sign with 'EUR'
$('input.foo').bind('keyup', '$', function(){
  this.value = this.value.replace('$', 'EUR');
});

Types

Supported types are 'keydown', 'keyup' and 'keypress'

Sequences

Handlers can be bound to a keypresses that contain a definable sequence of characters. For instance, pressing the g then a keys. The keypresses in the sequence must be executed within one second of each other to trigger the handler. Any number of characters can be required of a sequence and multiple sequences (seperated by a space) can be bound to the same handler.

jQuery(document).bind('keydown', 'g;a', function (evt) { alert('g then a'); });

Mac's Command Key

(08/2011 - v0.8.1 or >)
This fork adds support to the mac's command key, you can map a ctrl+[some key] and a command+[some key] simultaneously. So the shortcut is gonna works for mac users naturally like native hotkeys. See the follow example:

$(document).bind('keydown', 'ctrl+shift+space', function() {
  console.log('Yeah, you have the control!');
});

$(document).bind('keydown', 'command+shift+space', function() {
  console.log('OMG! How coll is that, huh!?');
});

Notes

If you want to use more than one modifiers (e.g. alt+ctrl+z) you should define them by an alphabetical order e.g. alt+ctrl+shift

Hotkeys aren't tracked if you're inside of an input element (unless you explicitly bind the hotkey directly to the input). This helps to avoid conflict with normal user typing.

jQuery Compatibility

Works with jQuery 1.4.2 and newer, even with the jQuery 1.6.2 (a little bit different from the 1.4.x series).

It known to be working with all the major browsers on all available platforms (Win/Mac/Linux)

  • IE 6/7/8
  • FF 1.5/2/3
  • Opera-9
  • Safari-3
  • Chrome-0.2

Addendum

Firefox is the most liberal one in the manner of letting you capture all short-cuts even those that are built-in in the browser such as Ctrl-t for new tab, or Ctrl-a for selecting all text. You can always bubble them up to the browser by returning true in your handler.

Others, (IE) either let you handle built-in short-cuts, but will add their functionality after your code has executed. Or (Opera/Safari) will not pass those events to the DOM at all.

So, if you bind Ctrl-Q or Alt-F4 and your Safari/Opera window is closed don't be surprised.