Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/avocode/combokeys
Web browser keyboard shortcuts. CommonJS, NPM.
https://github.com/avocode/combokeys
combokeys keyboard keyboard-shortcuts mousetrap
Last synced: 3 days ago
JSON representation
Web browser keyboard shortcuts. CommonJS, NPM.
- Host: GitHub
- URL: https://github.com/avocode/combokeys
- Owner: avocode
- License: apache-2.0
- Created: 2014-11-15T15:31:27.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-02-12T22:12:04.000Z (almost 3 years ago)
- Last Synced: 2024-12-13T01:31:52.302Z (10 days ago)
- Topics: combokeys, keyboard, keyboard-shortcuts, mousetrap
- Language: JavaScript
- Homepage:
- Size: 904 KB
- Stars: 675
- Watchers: 19
- Forks: 29
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Combokeys [![Build Status](https://travis-ci.org/avocode/combokeys.svg?branch=master)](https://travis-ci.org/avocode/combokeys) [![js-standard-style](https://raw.githubusercontent.com/feross/standard/master/badge.png)](https://github.com/feross/standard)
Combokeys is a JavaScript library for handling keyboard shortcuts in the browser.
It is licensed under the Apache 2.0 license.
It is around **3.3kb** minified and gzipped and **9.9kb** minified, has no external dependencies, and has been tested in the following browsers:
- Internet Explorer 6+ (test suite works in IE9+)
- Safari
- Firefox
- ChromeIt has support for ``keypress``, ``keydown``, and ``keyup`` events on specific keys, keyboard combinations, or key sequences.
## Fork notice
This project was forked from [ccampbell/mousetrap](https://github.com/ccampbell/mousetrap).
It was forked because pull–requests were not being reviewed.
This fork's author intends to review pull–requests.
Main changes are
1. Refactored as CommonJS
2. Doesn't automatically listen on the `document`. Instead, it is now a constructor and the element on which to listen must be provided on instantiation. Multiple instances possible.## Getting started
Get it on your page:
```js
var Combokeys;
Combokeys = require("combokeys");
```Instantiate it for the entire page:
```js
var combokeys = new Combokeys(document.documentElement);
```Or, instantiate it for one or more specific elements:
```js
var firstCombokeys = new Combokeys(document.getElementById("first"));
var secondCombokeys = new Combokeys(document.getElementById("second"));
```Add some combos!
```js
// single keys
combokeys.bind('4', function() { console.log('4'); });
firstCombokeys.bind("?", function() { console.log('show shortcuts!'); });
secondCombokeys.bind('esc', function() { console.log('escape'); }, 'keyup');// combinations
combokeys.bind('command+shift+k', function() { console.log('command shift k'); });// map multiple combinations to the same callback
combokeys.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
combokeys.bind('g i', function() { console.log('go to inbox'); });
combokeys.bind('* a', function() { console.log('select all'); });// any character (actual character inserted—triggered by the `keypress` event)
combokeys.bind('any-character', function () { console.log('some visual feedback') });// konami code!
combokeys.bind('up up down down left right left right b a enter', function() {
console.log('konami code');
});
```When you’re done with it, detach:
```js
combokeys.detach()
// and it will not listen on the element any more
```You can also bind the plus and minus keys conveniently:
```js
combokeys.bind(['mod+plus', 'mod+minus'], function(e) {
e.preventDefault();
console.log("Override browser zoom!");
});
```## Why Combokeys?
There are a number of other similar libraries out there so what makes this one different?
- CommonJS, [NPM](https://www.npmjs.org/package/combokeys).
- You can listen on multiple, specified elements simultaneously.
- You are not limited to ``keydown`` events (You can specify ``keypress``, ``keydown``, or ``keyup`` or let Combokeys 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### AMD usage
You can also build an AMD-compatible version by running `npm run build`. This creates a universally compatible ```dist/combokeys.js``` which, you can use via RequireJS, or include directly in a `````` tag with the global variable ```Combokeys```.
## Documentation
The most complete documentation is currently at [Mousetrap, the original project's website](http://craig.is/killing/mice). At the time of this writing, the only differences are in how you get it in your page (It is now a CommonJS module which does not define a global for itself) and that you must instantiate it before binding keys.
The public API consists of `.bind`, `.unbind`, `.trigger`, `.stopCallback`, `.detach` and `.reset`.
## Plugins
There are [some plugins](https://github.com/avocode/combokeys/tree/master/plugins). See their individual readme files.
### Bind dictionary
Allows you to make multiple bindings in a single ``Combokeys.bind`` call.
### Global bind
Allows you to set global bindings that work even inside of input fields.
### Pause/unpause
Allows you to temporarily prevent Combokeys events from firing.
### Record
Allows you to capture a keyboard shortcut or sequence defined by a user.