✨ Help support the maintenance of this package by sponsoring me.

Alpine.js Mousetrap

A simple library for handling keyboard shortcuts with Alpine.js.

About

This plugin adds a new x-mousetrap directive to all of your Alpine components that can be used to register keyboard shortcuts.

Installation

CDN

Include the following <script> tag in the <head> of your document, just before Alpine.

<script src="https://cdn.jsdelivr.net/npm/@danharrin/[email protected]/dist/alpine-mousetrap.js" defer></script>

NPM

npm install @danharrin/alpine-mousetrap --save-dev

Add the x-mousetrap directive to your project by importing the package before Alpine.js.

import Alpine from 'alpinejs'
import Mousetrap from '@danharrin/alpine-mousetrap'

Alpine.plugin(Mousetrap)

window.Alpine = Alpine
window.Alpine.start()

Usage

To register keyboard shortcuts for a button or other clickable element:

<div x-data="{}">
    <button
        type="button"
        x-mousetrap.command-k.ctrl-k
    >
        Button
    </button>
</div>

Check out the original Mousetrap documentation for more shortcut examples.

If the shortcut uses a +, replace it with a -. If the shortcut is a sequence, replace the space with --. If you're registering more than one shortcut, separate them with a period.

Alternatively, you can invoke a custom function when the keyboard shortcut is hit:

<div x-data="{}">
    <button
        type="button"
        x-mousetrap.command-k.ctrl-k="console.log('command k or control k')"
    >
        Button
    </button>
</div>

Global bindings

You may listen for "global" keyboard events that will work anywhere, including inside input fields:

<div x-data="{}">
    <button
        type="button"
        x-mousetrap.global.command-k.ctrl-k
    >
        Button
    </button>
</div>

Slash (/)

You may listen for "/" keypress events using the keyword "slash":

<div x-data="{}">
    <button
        type="button"
        x-mousetrap.global.slash
    >
        Button
    </button>
</div>

Versioning

This projects follow the Semantic Versioning guidelines.

License

Copyright (c) Dan Harrin

Licensed under the MIT license, see LICENSE.md for details.