HotkeyChord

type HotkeyChord = 
  | Key
  | SingleModifierHotkey
  | TwoModifierHotkey
  | ThreeModifierHotkey
  | FourModifierHotkey;

Defined in: hotkey.types.ts:126

A type-safe hotkey string.

Provides autocomplete for:

• All single keys (letters, numbers, function keys, navigation, editing, punctuation)
• Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
• Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
• Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
• Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)

Modifier Names#

Use canonical modifier names:

• Control (not Ctrl) - The Control key
• Alt (not Option) - The Alt key (Option on macOS)
• Meta (not Command/Cmd) - The Meta/Command key (macOS only)
• Shift - The Shift key

Platform-Adaptive Mod Modifier#

The Mod modifier is a special platform-adaptive modifier that automatically resolves to the "primary modifier" on each platform:

• macOS: Mod → Meta (Command key ⌘)
• Windows/Linux: Mod → Control (Ctrl key)

This enables cross-platform hotkey definitions that work correctly on all platforms without platform-specific code. The Mod modifier is resolved at runtime based on the detected platform.

When to use Mod vs platform-specific modifiers:

• Use Mod for cross-platform shortcuts (e.g., Mod+S for save)
• Use Meta or Control when you need platform-specific behavior
• Use Mod when you want your shortcuts to follow platform conventions automatically

Limitations:

• Mod+Control and Mod+Meta combinations are not allowed (they create duplicate modifiers on one platform)
• In four-modifier combinations, only canonical modifiers are allowed (no Mod)

Example#

// Cross-platform shortcuts (recommended)
const save: HotkeyChord = 'Mod+S'           // Command+S on Mac, Ctrl+S on Windows/Linux
const saveAs: HotkeyChord = 'Mod+Shift+S'   // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
const comment: HotkeyChord = 'Mod+/'       // Command+/ on Mac, Ctrl+/ elsewhere

// Platform-specific shortcuts
const macOnly: HotkeyChord = 'Meta+S'       // Command+S on Mac only
const windowsOnly: HotkeyChord = 'Control+S' // Ctrl+S on Windows/Linux only