# useHotkeys

## Usage

Registers global keyboard shortcuts with a single window `keydown` listener per hook instance. The shortcut list is read from a ref or getter, so updating it never re-subscribes. Skips events from typing targets (`input`, `textarea`, `select`, `contenteditable`) unless `allowInInputs`, skips `defaultPrevented` events, skips keys that belong to an IME composition, and calls `preventDefault()` on match. SSR-safe: the listener is only installed on mount.

```ts
import { useHotkeys } from '@astryx-vue/core'
```

The listener is removed when the component unmounts, not when the list changes.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use for app-level shortcuts like command palettes (`mod+k`), help overlays (`shift+/`), and navigation keys. |
| Do | Pair with the `Kbd` component to display the same combo you register; both resolve `mod` per platform identically. |
| Do | Use `isDisabled` to suspend shortcuts while a modal or wizard owns the keyboard, instead of unmounting the hook. |
| Don't | Use for focus-scoped keyboard navigation inside a widget; use `useListFocus` or `useGridRovingFocus` instead. |

## Parameters

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `hotkeys` | `MaybeRefOrGetter<readonly Hotkey[]>` | — | Shortcut registrations. A plain array, a ref, or a getter all work; the list is read on each key press. Required. |
| `hotkeys[].keys` | `string` | — | A `"+"`-separated combo like `"mod+k"`, `"shift+/"`, `"escape"`. `mod` is ⌘ on macOS and Ctrl elsewhere. Aliases: `esc`, `space`, `up`, `down`, `left`, `right`, `return`, and `plus` for a literal `+`. Without `shift` in the combo, the shift state is ignored, so a single letter does not care about case. |
| `hotkeys[].onPress` | `(event: KeyboardEvent) => void` | — | Called when the combo matches, after `preventDefault()`. |
| `hotkeys[].allowInInputs` | `boolean` | `false` | Lets the hotkey fire while typing in an input, textarea, select, or contenteditable region. |
| `hotkeys[].isDisabled` | `boolean` | `false` | Temporarily disables this entry without removing the listener. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| — | `void` | Nothing is returned. The window listener is removed when the component unmounts. |