useHotkey

Keyboard shortcuts with platform-aware mod keys.

HooksInteraction@gaudi/design-system/hooks/interaction/use-hotkeyView in Storybook Source

Runs a callback for a combination such as 'mod+k' (Command+K on macOS, Control+K elsewhere), 'shift+?' or 'escape'. Skips plain keys while the reader types in a field, and returns aria-keyshortcuts and Kbd keys for the hint.

Usage

import { useHotkey } from '@gaudi/design-system/hooks';
const { ariaKeyShortcuts, kbdKeys } = useHotkey('mod+k', () => setOpen(true));
<Button aria-keyshortcuts={ariaKeyShortcuts} onClick={() => setOpen(true)}>Search <Kbd keys={kbdKeys} /></Button>

Examples

Platform-aware mod key

Storybook

Single-key shortcuts that can be turned off

Storybook

API

7 options

2 return values

Accessibility

Every shortcut needs a visible control that does the same thing. Put aria-keyshortcuts on that control and show the keys with Kbd. Avoid single-key shortcuts unless they can be turned off (WCAG 2.1.4).

Notes

parseHotkey, matchHotkey, toAriaKeyShortcuts and toKbdKeys are exported for custom handling.

KbdKbd renders keyboard keys and multi-key shortcuts.2 examples useCopyToClipboardCopy text with a temporary copied state and a fallback.useEventListenerDeclarative DOM event listener with cleanup.useHoverPointer hover state with props to spread, ignoring touch.useMousePositionTrack viewport, page and optional element-relative pointer coordinates.useOnClickOutsideRun a callback when a press lands outside one or more elements.