Mousetrap - Keyboard Shortcuts Library

Prerequisites

• Runtime: Modern web browser (Internet Explorer 6+, Safari, Firefox, Chrome)
• Development: None required for basic usage
• Package Manager: Optional - npm for installation

Installation

Option 1: Direct Script Inclusion

1. Download the latest version from cdnjs
2. Include the script in your HTML before the closing </body> tag:

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

Option 2: npm Installation

1. Install via npm:

npm install mousetrap

2. Require in your JavaScript:

var Mousetrap = require('mousetrap');

Option 3: ES6 Modules

import Mousetrap from 'mousetrap';

Configuration

Mousetrap requires no configuration files or environment variables. It works out-of-the-box with default settings.

Optional Configuration

• Event Types: You can specify keypress, keydown, or keyup events when binding shortcuts
• International Keyboards: Automatically supports international keyboard layouts

Build & Run

Development

1. Include Mousetrap in your HTML file
2. Add keyboard event bindings in your JavaScript:

<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; // prevent default browser behavior
    });

    // 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>

Production

1. Use the minified version: mousetrap.min.js (4.5kb minified)
2. Consider using a CDN for faster loading:

<script src="https://cdnjs.cloudflare.com/ajax/libs/mousetrap/1.6.5/mousetrap.min.js"></script>

Deployment

Mousetrap is a client-side JavaScript library, so deployment is straightforward:

Static Hosting Options

• GitHub Pages: Perfect for documentation sites
• Netlify: Free hosting for static sites
• Vercel: Zero-config deployment
• AWS S3: For larger applications
• Cloudflare Pages: Fast global CDN

Framework Integration

• React/Vue/Angular: Include as a script tag or via npm
• WordPress: Add to theme header/footer
• Node.js: Use with Express or other frameworks

Troubleshooting

Common Issues

Issue: Keyboard shortcuts not working in text inputs Solution: Use bindGlobal() instead of bind() for shortcuts that should work in text fields:

Mousetrap.bindGlobal('ctrl+s', _saveChanges);

Issue: Conflicts with browser default shortcuts Solution: Return false from your callback to prevent default behavior:

Mousetrap.bind('ctrl+s', function() {
    saveDocument();
    return false; // prevents browser's default save dialog
});

Issue: Special keys not working Solution: Use the correct key names from the _MAP object:

• backspace, tab, enter, shift, ctrl, alt, esc, space
• pageup, pagedown, end, home, left, up, right, down
• ins, del, meta (command key on Mac)

Issue: Key sequences not working Solution: Ensure proper spacing between keys in sequences:

// Correct: space between keys
Mousetrap.bind('g i', function() { console.log('go to inbox'); });

// Incorrect: no space
Mousetrap.bind('gi', function() { console.log('won't work'); });

Testing

1. Browser Testing: Use the online test page to verify browser compatibility
2. Unit Tests: Run with Mocha if you're contributing to the project:

cd /path/to/repo
npm install
npm test

Performance Tips

• Use the minified version in production
• Only bind necessary shortcuts
• Consider unbinding shortcuts when not needed: Mousetrap.unbind('ctrl+s')
• Use trigger() method to programmatically fire shortcuts when needed

Browser Compatibility

Mousetrap has been tested in:

• Internet Explorer 6+
• Safari
• Firefox
• Chrome

If you encounter issues in specific browsers, check the test page or report issues on the GitHub repository.