# @mwillbanks/tuil-hotkeys

Source: /tuil/docs/reference/packages/hotkeys
Locale: en

Scoped terminal hotkeys, chords, and key sequences for tuil.



## Overview [#overview]

Scoped terminal hotkeys, chords, and key sequences for tuil.

`@mwillbanks/tuil-hotkeys` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-hotkeys
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-hotkeys
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-hotkeys
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-hotkeys
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Hotkey bindings normalize terminal input, match chords and sequences, honor active scopes, resolve priorities, and dispose cleanly.

<Mermaid
  chart="flowchart LR
  S0[&#x22;register&#x22;]
  S1[&#x22;scope match&#x22;]
  S2[&#x22;sequence match&#x22;]
  S3[&#x22;dispatch&#x22;]
  S4[&#x22;dispose&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                         | Signature                          | Description                              |
| ------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
| [`Hotkey`](/tuil/docs/reference/packages/hotkeys/api/hotkey)                                     | `function Hotkey`                  | Public function Hotkey.                  |
| [`HotkeyBinding`](/tuil/docs/reference/packages/hotkeys/api/hotkey-binding)                      | `interface HotkeyBinding`          | Public interface HotkeyBinding.          |
| [`HotkeyConflict`](/tuil/docs/reference/packages/hotkeys/api/hotkey-conflict)                    | `interface HotkeyConflict`         | Public interface HotkeyConflict.         |
| [`HotkeyDispatchContext`](/tuil/docs/reference/packages/hotkeys/api/hotkey-dispatch-context)     | `interface HotkeyDispatchContext`  | Public interface HotkeyDispatchContext.  |
| [`HotkeyEvent`](/tuil/docs/reference/packages/hotkeys/api/hotkey-event)                          | `interface HotkeyEvent`            | Public interface HotkeyEvent.            |
| [`HotkeyLayer`](/tuil/docs/reference/packages/hotkeys/api/hotkey-layer)                          | `function HotkeyLayer`             | Public function HotkeyLayer.             |
| [`HotkeyManager`](/tuil/docs/reference/packages/hotkeys/api/hotkey-manager)                      | `class HotkeyManager`              | Public class HotkeyManager.              |
| [`HotkeyMetadata`](/tuil/docs/reference/packages/hotkeys/api/hotkey-metadata)                    | `interface HotkeyMetadata`         | Public interface HotkeyMetadata.         |
| [`HotkeyProvider`](/tuil/docs/reference/packages/hotkeys/api/hotkey-provider)                    | `function HotkeyProvider`          | Public function HotkeyProvider.          |
| [`HotkeyScope`](/tuil/docs/reference/packages/hotkeys/api/hotkey-scope)                          | `type HotkeyScope`                 | Public type HotkeyScope.                 |
| [`normalizeHotkeyNotation`](/tuil/docs/reference/packages/hotkeys/api/normalize-hotkey-notation) | `function normalizeHotkeyNotation` | Public function normalizeHotkeyNotation. |
| [`normalizeTerminalKey`](/tuil/docs/reference/packages/hotkeys/api/normalize-terminal-key)       | `function normalizeTerminalKey`    | Public function normalizeTerminalKey.    |
| [`TerminalKey`](/tuil/docs/reference/packages/hotkeys/api/terminal-key)                          | `interface TerminalKey`            | Public interface TerminalKey.            |
| [`useHotkey`](/tuil/docs/reference/packages/hotkeys/api/use-hotkey)                              | `function useHotkey`               | Public function useHotkey.               |
| [`useHotkeyManager`](/tuil/docs/reference/packages/hotkeys/api/use-hotkey-manager)               | `function useHotkeyManager`        | Public function useHotkeyManager.        |
| [`useHotkeys`](/tuil/docs/reference/packages/hotkeys/api/use-hotkeys)                            | `function useHotkeys`              | Public function useHotkeys.              |

## Events and lifecycle [#events-and-lifecycle]

Bindings invoke handlers directly. Dispatch failures are routed to the caller-supplied error handler.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
hotkeys.register({ keys: "ctrl+s", scope: "application", handler: save });
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)