hotkeypad
v0.1.1
Published
HotKeyPad: A simple and beautiful command keyboard shortcut for your web app.
Downloads
1,023
Maintainers
Readme
HotKeyPad
HotKeypad is a lightweight package that provides you with a keyboard shortcuts interface for your website. Built with vanilla JS, no external dependencies. Inspired in design and functionality by NinjaKeys.
Demo
Motivation
There are lots of libraries that provide keyboard shortcuts for web apps, but most of them are somewhat heavy and depend on extra dependencies. I wanted to create a simple and lightweight package that provided this functionality without any dependencies and made with vanilla JS, so it could be integrated into any web project.
Installation
You can install hotkeypad via npm, pnpm or yarn. Here's how you can do it with npm:
npm install hotkeypad
Usage
To use HotKeyPad, you need to import the package and create a new instance of the HotKeyPad class. You can then add commands to the keypad and display it on your web app.
First, add thee following tag to your page:
<div id="hotkeypad"></div>
Then, you can use the following code to add the keypad to your page:
import HotKeyPad from 'hotkeypad'
const hotkeypad = new HotKeyPad()
// This will set the commands and render the keypad automatically
hotkeypad.setCommands([
{
section: "Actions",
id: "print",
title: "Print Page",
icon: `#custom-icon-print#`, // You can insert your own icon here, being and svg, image or font icon
hotkey: `${hotKeyPad.activationKey} + P`, // You can use the default activation key or set your own
handler: () => {
window.print()
}
},
])
// You can also add a listener to the open and close events
window.addEventListener('hotkeypad:open', () => {
console.log('HotKeyPad is open')
})
window.addEventListener('hotkeypad:close', () => {
console.log('HotKeyPad is closed')
})
The default activation key is Ctrl
for Windows/Linux and Cmd
for Mac.
Features
- Keyboard navigation
- Customizable commands
- Light and dark mode support
- Customizable colors with CSS variables
- Customizable activation key
Attributes
You can pass the following attributes to the HotKeyPad
constructor or to the html tag (data- prefix is required with kebab-case for the attribute name).
| Field | Default | Description |
|-------------|----------------|---------------------------------------------------------|
| placeholder | Search command | Placeholder text for the search input. |
| activationLetter | K
| The activation letter for the commands. Default is K
. |
| closeKey | Escape
| The key to close the keypad. Default is Escape
. |
Commands Format
Array of HotKeyPadData that represent the commands that will be displayed on the keypad.
| Field | Type | Description |
|-----------|----------|-----------------------------------------------------------------------------|
| id | string | The unique identifier of the command. |
| title | string | The title of the command. |
| hotkey | string | The hotkey combination for the command. Format: {ActivationKey}+{Letter}
|
| handler | Function | The function to be executed when the command is triggered. |
| icon | string (optional) | The icon of the command. |
| section | string (optional) | The section of the command. Allows you to group commands. |
Methods
setCommands(commands: HotKeyPadData[]): void
Set the commands that will be displayed on the keypad.
open(): void
Open the keypad.
close(): void
Close the keypad.
Events
hotkeypad:open
Fired when the keypad is opened.
hotkeypad:close
Fired when the keypad is closed.
CSS Variables
You can customize the colors of the keypad by changing the CSS variables. Here are the available variables:
--hotkeypad-bg-kbd: #f9fafb;
--hotkeypad-bg-backdrop: #fff;
--hotkeypad-bg-container: #fff;
--hotkeypad-bg-item-hover: #f3f4f6;
--hotkeypad-border-container: #d1d5db;
--hotkeypad-border-container-hover: #9ca3af;
--hotkeypad-fg-muted: #4b5563;
Example:
#hotkeypad {
--hotkeypad-bg-container: red;
}
CSS HotKeyPad Parts
Allowing you to style specific elements from your style.
#hotkeypad [data-backdrop] {}
#hotkeypad [data-container] {}
#hotkeypad [data-sections] {}
#hotkeypad [data-section] {}
#hotkeypad [data-hotkey] {}
#hotkeypad [data-hotkey][data-active] {}
Icons
You can use any icon library or custom icons. You can use the icon
field to set the icon of the command. You can use an image, svg or font icon:
<svg ...><path d="..." /></svg>
<img src="path/to/image.png" alt="Title" />
<i class="material-icons">print</i>
By default will use the Simple Icons library as this: <img src="https://cdn.simpleicons.org/{icon}" alt="{title}" />
if you pass a normal name instead of the any previous mentioned tags.
License
Copyright (c) Jesus Borrero.
Licensed under the MIT License