Neutron Polarization Manipulator

    stimulus-shortcut

    1.0.3 • Public • Published

    Stimulus Shortcut

    npm version

    A Stimulus controller for mapping keystrokes to element events Tiny at ~60 LOC


    • Simple: with only one parameter, this is a drop-in, code-free solution
    • Backend Agnostic: 100% client-side
    • Flexible: built on the amazing HotKeys.js library
    • Idempotent: compatible with Turbolinks by design
    • MIT Licensed: free for personal and commercial use

    Built for StimulusJS

    This Stimulus controller allows you to detect a keyboard shortcut and trigger the default action of the element the controller is attached to. This is an easy way to create shortcut keys for your application. Once registered in your Stimulus application, you can use it anywhere you like.

    This controller is the sister to stimulus-hotkeys and since they share the same dependency, both can be used in the same project to great effect.

    Here is a simple example, in which the user hits the p key and it will "click" the link.

    <a data-controller="shortcut" data-shortcut-key-value="p">Type 'p' to activate me!</a>

    Yes, that's really it.

    Credit where credit is due

    This package would be nothing without Hotkeys. Thank you, Kenny Wong!

    The idea for this variation on stimulus-hotkeys was inspired by and borrows code extensively from Stephen Margheim aka @fractaledmind.

    Setup

    Note: stimulus-shortcut requires StimulusJS v2.0 or later

    Add stimulus-shortcut to your main JS entry point or Stimulus controllers root folder:

    import { Application } from 'stimulus'
    import Shortcut from 'stimulus-shortcut'
    
    import { definitionsFromContext } from 'stimulus/webpack-helpers'
    const application = Application.start()
    const context = require.context('../controllers', true, /\.js$/)
    application.load(definitionsFromContext(context))
    
    // Manually register Shortcut as a Stimulus controller
    application.register('shortcut', Shortcut)

    HTML Markup

    The data-shortcut-key-value attribute accepts a string representing a Hotkeys key combination. You will want to learn about possible key combinations on the Hotkeys project page.

    This controller follows the Stimulus default event shorthand and defaults to the click event. However, you can specify any event - browser or custom - by specifying the data-shortcut-event-value attribute.

    Here is an example where pressing the m key raises the mouseover event on an img element.

    <img src="image.jpg" data-controller="shortcut" data-shortcut-key-value="m" data-shortcut-event-value="mouseover">

    Note: data-shortcut-key-value is a mandatory attribute. If you don't define a key to capture, the controller will remove itself from the element and a console warning will be raised.

    Obtaining a reference to the Stimulus controller instance

    I'm usually a huge fan of putting a reference to the controller on the element holding the controller, but this library literally has no functions which can be called from outside. If you're trying to do this, you're doing something very wrong.

    Contributing

    Bug reports and pull requests are welcome.

    License

    This package is available as open source under the terms of the MIT License.

    Install

    npm i stimulus-shortcut

    DownloadsWeekly Downloads

    23

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    187 kB

    Total Files

    11

    Last publish

    Collaborators

    • leastbad