Rails gem for handling keyboard shortcuts via mousetrap javascript library
Ruby CSS HTML CoffeeScript JavaScript
Failed to load latest commit information.
lib Bump version to 1.4.6. Now mousetrap-rails has the same version as mo… Nov 25, 2013
spec Remove AR fixtures from spec helper Jun 13, 2013
Gemfile Initial commit Sep 22, 2012
LICENSE.md Update license, changelog and readme Feb 12, 2013
Rakefile Minor tasks refactoring Dec 12, 2014
gem-public_cert.pem Sign gem with selfsigned cert Jan 31, 2013
mousetrap-rails.gemspec Temporarily disable signature Jun 11, 2013



Gem Version Dependency Status Code Climate Build Status Coverage Status Gratipay Downloads

Mousetrap is a javascript library for handling keyboard shortcuts in your web applications written by Craig Campbell.

The mousetrap-rails gem integrates Mousetrap javascript library with Rails asset pipeline.


Add mousetrap-rails gem to app

Add this line to your application's Gemfile:

gem 'mousetrap-rails'

And then execute:

$ bundle install

Run generator

$ rails generate mousetrap:install

It will create a sample keybindings.js.coffee file in app/assets/javascripts and insert mousetrap-rails files to manifests of asset pipeline

//= require mousetrap     # ---> application.js
*= require mousetrap      # ---> application.css


Also you can use mousetrap plugins. Require them in your application.js file

//= require mousetrap/plugins       # To require all plugins
//= require mousetrap/dictionary    # To require dictionary plugin
//= require mousetrap/global        # To require global plugin
//= require mousetrap/pause         # To require pause plugin
//= require mousetrap/record        # To require record plugin

See plugin descriptions below.

Latest (may be unstable) version

Instead of gem 'mousetrap-rails' add to your Gemfile

gem 'mousetrap-rails', github: 'kugaevsky/mousetrap-rails'

Mousetrap-rails versioning use mousetrap.js library version number.


Via data-attributes

You can add keyboard navigation to your links by using data-keybinding attribute.

= link_to 'Homepage', root_path, data: { keybinding: 'h' }          # Press 'h' to navigate to homepage
= link_to 'About', about_path, data: { keybinding: '["a", "c"]' }   # Press 'a' or 'c' to navigate to about

You can jump to an input

= text_field_tag 'Username', nil, data: { keybinding: 'u' }         # Press 'u' to focus username input field

Via javascript

Any javascript function can be called with mousetrap

Mousetrap.bind 'f', (e) -> alert 'My perfect function called'       # Press 'f' to popup alert

More examples (from official guide)

# single keys
Mousetrap.bind '4', -> alert '4 pressed!'
Mousetrap.bind 'x', (-> alert 'x pressed!'), 'keyup'

# combinations
Mousetrap.bind 'command+shift+k', ->
  alert 'command+shift+k pressed!'

Mousetrap.bind ['command+k', 'ctrl+k'], ->
  alert 'command+k or ctrl+k pressed!'

# gmail style sequences
Mousetrap.bind 'g i', -> console.log 'g i sequence pressed!'
Mousetrap.bind '* a', -> console.log '* a sequence pressed!'

# konami code!
Mousetrap.bind 'up up down down left right left right b a enter', -> console.log 'You WIN!'

You can find full documentation on Mousetrap library page. Really, look there – there are plenty examples of using this awesome library.

Key binding hints (experimental)

You can display key binding hints near links with data-keybinding attribute by pressing Alt+Shift+h. Now it's just experimental feature for debugging purposes only.


Global Bindings

//= require mousetrap/global        # ---> application.js

This extension allows you to specify keyboard events that will work anywhere including inside textarea/input fields.

Mousetrap.bindGlobal 'ctrl+s', -> _save()

This means that a keyboard event bound using Mousetrap.bind will only work outside of form input fields, but using Moustrap.bindGlobal will work in both places.

Bind dictionary

//= require mousetrap/dictionary        # ---> application.js

This extension overwrites the default bind behavior and allows you to bind multiple combinations in a single bind call.

Usage looks like:

    'a': -> console.log('a')
    'b': -> console.log('b')

You can optionally pass in keypress, keydown or keyup as a second argument.

Other bind calls work the same way as they do by default.


//= require mousetrap/pause             # ---> application.js

This extension allows Mousetrap to be paused and unpaused without having to reset keyboard shortcuts and rebind them.

# stop Mousetrap events from firing

# allow Mousetrap events to fire again


//= require mousetrap/record              # ---> application.js

This extension lets you use Mousetrap to record keyboard sequences and play them back:

button onclick="recordSequence()" Record
recordSequence = () ->
  Mousetrap.record (sequence) ->
    # sequence is an array like ['ctrl+k', 'c']
    alert('You pressed: ' + sequence.join(' '))

More detailed plugins description


Please submit all pull requests against latest *.wip branch. If your pull request contains new features, you must include relevant tests.

You can easily update mousetrap.js library via rake tasks.

$ rake mousetrap:update          # Update main mousetrap javascript lib and its plugins
$ rake mousetrap:update:main     # Update main mousetrap javascript lib
$ rake mousetrap:update:plugins  # Update mousetrap javascript lib plugins

Thanks in advance!


All changes could be found in CHANGELOG.md


Gosh! It's here.


Bitdeli Badge Flattr this endorse