Skip to main content

​
Quickstart

Get HotkeyPad up and running in your website in just a few steps.

​
Prerequisites

Make sure you have installed HotkeyPad via npm or CDN.

​
Basic setup

1

Add the container element

Add a div with the ID hotkeypad to your HTML page:
<div id="hotkeypad"></div>
This element must have the ID hotkeypad. HotkeyPad will throw an error if it can’t find this element.
2

Import and initialize HotkeyPad

Import HotkeyPad, its CSS, and create a new instance:
import HotKeyPad from 'hotkeypad'
import 'hotkeypad/index.css'

const hotkeypad = new HotKeyPad()
The activation key is automatically set to Cmd+K on macOS and Ctrl+K on Windows/Linux.
3

Define your commands

Create an array of commands with keyboard shortcuts:
const commands = [
  {
    id: 'print',
    title: 'Print Page',
    hotkey: 'Ctrl + P',
    handler: () => {
      window.print()
    }
  },
  {
    id: 'home',
    title: 'Go to Home',
    hotkey: 'Ctrl + H',
    section: 'Navigation',
    handler: () => {
      window.location.href = '/'
    }
  }
]
Each command requires:
  • id: Unique identifier
  • title: Display name in the command palette
  • hotkey: Keyboard combination (format: Modifier + Key)
  • handler: Function to execute when triggered
4

Set commands and render

Apply your commands to the HotkeyPad instance:
hotkeypad.setCommands(commands)
This method validates your commands and automatically renders the keyboard shortcut interface.

​
Complete example

Here’s a complete working example:
index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>HotkeyPad Demo</title>
  <link rel="stylesheet" href="https://unpkg.com/hotkeypad/dist/styles/index.css">
</head>
<body>
  <h1>Press Cmd+K (or Ctrl+K) to open commands</h1>
  
  <div id="hotkeypad"></div>

  <script type="module">
    import HotKeyPad from 'https://unpkg.com/hotkeypad?module'

    const hotkeypad = new HotKeyPad()

    hotkeypad.setCommands([
      {
        id: 'print',
        title: 'Print Page',
        hotkey: 'Ctrl + P',
        section: 'Actions',
        handler: () => {
          window.print()
        }
      },
      {
        id: 'home',
        title: 'Go to Home',
        hotkey: 'Ctrl + H',
        section: 'Navigation',
        handler: () => {
          window.location.href = '/'
        }
      },
      {
        id: 'search',
        title: 'Search',
        hotkey: 'Ctrl + F',
        section: 'Actions',
        icon: 'google',
        handler: () => {
          window.open('https://google.com', '_blank')
        }
      }
    ])
  </script>
</body>
</html>

​
Try it out

  1. Press Cmd+K (macOS) or Ctrl+K (Windows/Linux) to open the command palette
  2. Use arrow keys or Tab to navigate commands
  3. Press Enter to execute a command, or click on it
  4. Press Escape or Cmd+K/Ctrl+K again to close
  5. Type to search through commands

​
Adding icons

You can add icons to your commands in multiple ways: 
const command = {
  id: 'github',
  title: 'Open GitHub',
  hotkey: 'Ctrl + G',
  icon: 'github', // Uses Simple Icons CDN
  handler: () => window.open('https://github.com', '_blank')
}
By default, HotkeyPad uses Simple Icons. Just pass the icon name (e.g., "github", "react", "typescript") and it automatically loads from the CDN.

​
Configuration options

Customize HotkeyPad behavior when creating an instance: 
const hotkeypad = new HotKeyPad({
  placeholder: 'Type a command...',
  emptyMessage: 'No matching commands',
  activationLetter: 'K',
  closeKey: 'Escape'
})
All configuration options are optional. HotkeyPad works with sensible defaults out of the box.

​
Using dynamic activation key

The activation key differs by platform (Cmd on macOS, Ctrl on Windows/Linux). Access it dynamically: 
const hotkeypad = new HotKeyPad()

const commands = [
  {
    id: 'print',
    title: 'Print Page',
    hotkey: `${hotkeypad.activationKey} + P`, // Automatically 'Cmd' or 'Ctrl'
    handler: () => window.print()
  }
]

​
Listening to events

HotkeyPad emits custom events when opened or closed: 
window.addEventListener('hotkeypad:open', () => {
  console.log('Command palette opened')
})

window.addEventListener('hotkeypad:close', () => {
  console.log('Command palette closed')
})

​
Grouping commands

Organize commands into sections using the optional section property: 
hotkeypad.setCommands([
  {
    id: 'home',
    title: 'Go Home',
    hotkey: 'Ctrl + H',
    section: 'Navigation',
    handler: () => window.location.href = '/'
  },
  {
    id: 'about',
    title: 'About Page',
    hotkey: 'Ctrl + A',
    section: 'Navigation',
    handler: () => window.location.href = '/about'
  },
  {
    id: 'print',
    title: 'Print',
    hotkey: 'Ctrl + P',
    section: 'Actions',
    handler: () => window.print()
  }
])
Commands without a section property are grouped under “Unlisted” without a visible header.

​
Next steps

API Reference

Explore all methods, types, and configuration options

Customization

Learn how to style HotkeyPad with CSS variables

Examples

See real-world use cases and advanced patterns

Events

Work with HotkeyPad events and programmatic control

Build docs developers (and LLMs) love

Get started for freeTalk to us