README.md
102 lines
| 1 | # Mousetrap |
| 2 | [](https://cdnjs.com/libraries/mousetrap](https://cdnjs.com/libraries/mousetrap](https://cdnjs.com/libraries/mousetrap) |
| 3 | |
| 4 | Mousetrap is a simple library for handling keyboard shortcuts in Javascript. |
| 5 | |
| 6 | It is licensed under the Apache 2.0 license. |
| 7 | |
| 8 | It is around **2kb** minified and gzipped and **4.5kb** minified, has no external dependencies, and has been tested in the following browsers: |
| 9 | |
| 10 | - Internet Explorer 6+ |
| 11 | - Safari |
| 12 | - Firefox |
| 13 | - Chrome |
| 14 | |
| 15 | It has support for `keypress`, `keydown`, and `keyup` events on specific keys, keyboard combinations, or key sequences. |
| 16 | |
| 17 | ## Getting started |
| 18 | |
| 19 | 1. Include mousetrap on your page before the closing `</body>` tag |
| 20 | |
| 21 | ```html |
| 22 | <script src="/path/to/mousetrap.min.js"></script> |
| 23 | ``` |
| 24 | |
| 25 | or install `mousetrap` from `npm` and require it |
| 26 | |
| 27 | ```js |
| 28 | var Mousetrap = require('mousetrap'); |
| 29 | ``` |
| 30 | |
| 31 | 2. Add some keyboard events to listen for |
| 32 | |
| 33 | ```html |
| 34 | <script> |
| 35 | // single keys |
| 36 | Mousetrap.bind('4', function() { console.log('4'); }); |
| 37 | Mousetrap.bind("?", function() { console.log('show shortcuts!'); }); |
| 38 | Mousetrap.bind('esc', function() { console.log('escape'); }, 'keyup'); |
| 39 | |
| 40 | // combinations |
| 41 | Mousetrap.bind('command+shift+k', function() { console.log('command shift k'); }); |
| 42 | |
| 43 | // map multiple combinations to the same callback |
| 44 | Mousetrap.bind(['command+k', 'ctrl+k'], function() { |
| 45 | console.log('command k or control k'); |
| 46 | |
| 47 | // return false to prevent default browser behavior |
| 48 | // and stop event from bubbling |
| 49 | return false; |
| 50 | }); |
| 51 | |
| 52 | // gmail style sequences |
| 53 | Mousetrap.bind('g i', function() { console.log('go to inbox'); }); |
| 54 | Mousetrap.bind('* a', function() { console.log('select all'); }); |
| 55 | |
| 56 | // konami code! |
| 57 | Mousetrap.bind('up up down down left right left right b a enter', function() { |
| 58 | console.log('konami code'); |
| 59 | }); |
| 60 | </script> |
| 61 | ``` |
| 62 | |
| 63 | ## Why Mousetrap? |
| 64 | |
| 65 | There are a number of other similar libraries out there so what makes this one different? |
| 66 | |
| 67 | - There are no external dependencies, no framework is required |
| 68 | - You are not limited to `keydown` events (You can specify `keypress`, `keydown`, or `keyup` or let Mousetrap choose for you). |
| 69 | - 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 |
| 70 | - It works with international keyboard layouts |
| 71 | - You can bind Gmail like key sequences in addition to regular keys and key combinations |
| 72 | - You can programatically trigger key events with the `trigger()` method |
| 73 | - It works with the numeric keypad on your keyboard |
| 74 | - The code is well documented/commented |
| 75 | |
| 76 | ## Tests |
| 77 | |
| 78 | Unit tests are run with <a href="https://mochajs.org/">mocha</a>. |
| 79 | |
| 80 | ### Running in browser |
| 81 | |
| 82 | [View it online](http://rawgit.com/ccampbell/mousetrap/master/tests/mousetrap.html) to check your browser compatibility. You may also download the repo and open `tests/mousetrap.html` in your browser. |
| 83 | |
| 84 | ### Running with Node.js |
| 85 | |
| 86 | 1. Install development dependencies |
| 87 | |
| 88 | ```sh |
| 89 | cd /path/to/repo |
| 90 | npm install |
| 91 | ``` |
| 92 | |
| 93 | 3. Run tests |
| 94 | |
| 95 | ```sh |
| 96 | npm test |
| 97 | ``` |
| 98 | |
| 99 | ## Documentation |
| 100 | |
| 101 | Full documentation can be found at https://craig.is/killing/mice |
| 102 |