UnflowUI
ComponentsHooks

useHotkey

Detects a keyboard combo and fires an action callback. Returns platform-aware visual representations of the keys for use in Shortcut or tooltips.

Overview

useHotkey fires a callback when all the given keys are held at the same time, anywhere on the page. It also returns the keys as ReactNode[], with modifier keys rendered as platform icons, ready to show next to an action.

Shortcut, ActionCard (through Shortcut), ItemNav and CommandPalette use it. Call it directly when you need a global shortcut, with or without the visual badge.

Import

import { useHotkey, resolveModKey } from '@unflowio/ui/hooks/useHotkey';

Parameters

ParamTypeDefaultDescription
keysstring[]undefinedKeys in MDN KeyboardEvent.key format. Mod is ⌘ on Apple platforms, Ctrl elsewhere
action(args?: T) => voidundefinedCallback to fire when the combo is pressed. It is called with no arguments. Without it, nothing is registered
listenbooleantrueEnables/disables the listener
allowRepeatbooleanfalseFire on key repeat (holding the key)

Return value

FieldTypeDescription
activebooleanWhether all keys are currently held
isHotkeyValidbooleanWhether the config is complete and listening
hotkeyReactNode[]Platform-rendered key labels. When not listening, arrows and Escape render as ↑ ↓ ← → and Esc
isMacbooleanWhether the platform was detected as macOS. false on the server and the first client render

Usage

Basic global shortcut

const { hotkey } = useHotkey({
  keys: ['Mod', 'k'],
  action: openSearch,
});

// Render the shortcut badge manually
return <div className="flex gap-1">{hotkey}</div>;

Conditional listener

const { isHotkeyValid, hotkey } = useHotkey({
  keys: selectedKeys,
  action: performAction,
  listen: isDialogOpen,  // only active while dialog is open
});

Check validity before rendering

isHotkeyValid is true only when listen is true, keys is non-empty, and action is defined. Use it to conditionally render the shortcut badge:

{isHotkeyValid && (
  <div className="flex gap-0.5">{hotkey}</div>
)}

Key naming

Keys follow MDN KeyboardEvent.key:

['Mod', 'k']             // ⌘K on macOS, Ctrl+K elsewhere
['Meta', 'k']            // ⌘K
['Control', 'Shift', 's'] // ⌃⇧S
['Alt', 'p']              // ⌥P (Mac) or Alt+P (Win)
['Enter']                 // Enter

Platform awareness

KeymacOS renderOther platforms
Mod⌘ iconCTRL
Meta⌘ iconWindows logo icon
Alt⌥ iconAlt
Control⌃ iconCTRL
Shift⇧ icon⇧ icon
OtherThe key as writtenThe key as written

The platform is read from navigator.platform after mount, so the first render (and server rendering) uses the non-Mac labels.

Blacklisted keys

The following keys are never part of a registered combo. They only render, as glyphs, when the hook is not listening (a passive legend):

  • Arrow keys (ArrowDown, ArrowUp, ArrowLeft, ArrowRight)
  • Escape
  • , (comma — used as a separator in some key string formats)

These conflict with focus management (arrows, Escape) and could cause unexpected behavior if registered globally.

Normalization

Keys are lowercased and sorted before registration. This means:

useHotkey({ keys: ['Control', 'K'], action })
useHotkey({ keys: ['k', 'control'], action })
// Both register the same combo

resolveModKey

resolveModKey(key: string, isMac: boolean): string

Returns 'Meta' on Apple platforms and 'Control' elsewhere when key is Mod (any case), and key unchanged otherwise. Use it to build an accessible name for a shortcut, as Shortcut does for its aria-label:

const { hotkey, isMac } = useHotkey({ keys, action });
const label = keys.map((key) => resolveModKey(key, isMac)).join('+');

Implementation notes

All useHotkey calls share one keydown/keyup listener on window. Every registered entry whose keys match fires, so two components listening for the same combo both run their action; use listen to keep only one active. A match calls preventDefault() and stopPropagation() on the event, so the browser's own shortcut for that combo doesn't run.

Held keys are cleared when Meta is released, when the window loses focus and when the tab is hidden, so a combo never stays stuck after switching apps.