mousetrap

What is mousetrap?

Mousetrap is a simple library for handling keyboard shortcuts in Javascript. It allows you to bind key combinations to specific functions, making it easier to create keyboard-driven interfaces.

What are mousetrap's main functionalities?

Binding a single key

This feature allows you to bind a single key to a function. In this example, pressing the 'A' key will trigger an alert.

Mousetrap.bind('a', function() { alert('You pressed A!'); });

Binding a combination of keys

This feature allows you to bind a combination of keys to a function. In this example, pressing 'Ctrl+S' will trigger an alert and prevent the default browser action.

Mousetrap.bind('ctrl+s', function(e) { e.preventDefault(); alert('You pressed Ctrl+S!'); });

Binding sequences of keys

This feature allows you to bind sequences of keys to a function. In this example, pressing 'G' followed by 'I' will trigger an alert.

Mousetrap.bind('g i', function() { alert('You pressed G then I!'); });

Binding keys in a specific context

This feature allows you to bind keys in a specific context, such as 'keydown', 'keyup', or 'keypress'. In this example, pressing 'Command/Control+Enter' will trigger an alert on the 'keydown' event.

Mousetrap.bind('mod+enter', function() { alert('You pressed Command/Control+Enter!'); }, 'keydown');

Unbinding keys

This feature allows you to unbind a previously bound key. In this example, the 'A' key will no longer trigger any function.

Mousetrap.unbind('a');

Other packages similar to mousetrap

keymaster

Keymaster is a simple micro-library for defining and dispatching keyboard shortcuts. It is similar to Mousetrap in that it allows you to bind key combinations to functions, but it is more lightweight and has a simpler API.

hotkeys-js

Hotkeys-js is a robust library for handling keyboard shortcuts. It offers more features than Mousetrap, such as support for key sequences and key scopes, making it a more versatile option for complex applications.

keyboardjs

KeyboardJS is a library for handling keyboard input. It provides a more comprehensive set of features compared to Mousetrap, including support for key sequences, key combos, and key states, making it suitable for more advanced use cases.

README

Mousetrap

Mousetrap is a simple library for handling keyboard shortcuts in Javascript.

It is licensed under the Apache 2.0 license.

It is around 1.9kb minified and gzipped and 3.5kb minified, has no external dependencies, and has been tested in the following browsers:

• Internet Explorer 6+
• Safari
• Firefox
• Chrome

It has support for keypress, keydown, and keyup events on specific keys, keyboard combinations, or key sequences.

If you would like to donate to help support Mousetrap development use Gittip.

Getting started

1. Include mousetrap on your page before the closing </body> tag

   <script src="/path/to/mousetrap.min.js"></script>
   

2. Add some keyboard events to listen for

   <script>
       // single keys
       Mousetrap.bind('4', function() { console.log('4'); });
       Mousetrap.bind("?", function() { console.log('show shortcuts!'); });
       Mousetrap.bind('esc', function() { console.log('escape'); }, 'keyup');
   
       // combinations
       Mousetrap.bind('command+shift+k', function() { console.log('command shift k'); });
   
       // map multiple combinations to the same callback
       Mousetrap.bind(['command+k', 'ctrl+k'], function() {
           console.log('command k or control k');
   
           // return false to prevent default browser behavior
           // and stop event from bubbling
           return false;
       });
   
       // gmail style sequences
       Mousetrap.bind('g i', function() { console.log('go to inbox'); });
       Mousetrap.bind('* a', function() { console.log('select all'); });
   
       // konami code!
       Mousetrap.bind('up up down down left right left right b a enter', function() {
           console.log('konami code');
       });
   </script>
   

Why Mousetrap?

There are a number of other similar libraries out there so what makes this one different?

• There are no external dependencies, no framework is required
• You are not limited to keydown events (You can specify keypress, keydown, or keyup or let Mousetrap choose for you).
• You can bind key events directly to special keys such as ? or * without having to specify shift+/ or shift+8 which are not consistent across all keyboards
• It works with international keyboard layouts
• You can bind Gmail like key sequences in addition to regular keys and key combinations
• You can programatically trigger key events with the trigger() method
• It works with the numeric keypad on your keyboard
• The code is well documented/commented

Tests

Unit tests run via mocha.

Running in browser

Download the repo and go to tests/mousetrap.html in your browser.

Running with Grunt and PhantomJS

1. Install grunt-cli

   npm install -g grunt-cli
   

2. Install npm packages

   cd /path/to/repo
   npm install
   

3. Run tests

   grunt mocha
   

Documentation

Full documentation can be found at http://craig.is/killing/mice