# github/hotkey architecture

> Architecture diagram of the GitHub repository github/hotkey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/hotkey
- Repository: https://github.com/github/hotkey

## Overview

@github/hotkey is a browser-side hotkey library. Callers install it on elements (usually those declared with data-hotkey); the library registers a document keydown handler, matches normalized keys and sequences, applies scope rules, then emits a cancellable event and defaults to focusing form fields or clicking other elements. The README also documents aliases, modifier and platform normalization, and unregistering. The graph follows sampled runtime imports and calls; broader documented usage is represented without assuming unsampled implementation details.

Main entry points: [`src/index.ts`](https://github.com/github/hotkey/blob/main/src/index.ts) (Install / uninstall), [`src/hotkey.ts`](https://github.com/github/hotkey/blob/main/src/hotkey.ts) (Event serialization), [`src/radix-trie.ts`](https://github.com/github/hotkey/blob/main/src/radix-trie.ts) (Hotkey trie), [`src/utils.ts`](https://github.com/github/hotkey/blob/main/src/utils.ts) (Alias expansion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Registration API"]
  node_install["Install / uninstall<br/>[index.ts]"]
  node_handler["Keydown handler<br/>[index.ts]"]
end

subgraph group_matching["Key Matching"]
  node_trie["Hotkey trie<br/>[radix-trie.ts]"]
  node_tracker["Sequence tracker<br/>[sequence.ts]"]
  node_expand["Alias expansion<br/>[utils.ts]"]
end

subgraph group_actions["Dispatch and Actions"]
  node_action["Action dispatch<br/>[utils.ts]"]
end

subgraph group_normalization["Key Normalization"]
  node_serialize["Event serialization<br/>[hotkey.ts]"]
  node_normalize["Hotkey normalization<br/>[hotkey.ts]"]
  node_macsymbols["Mac symbol map"]
  node_macuppercase["Mac uppercase map"]
end

node_caller(("Integrating page"))
node_target["Target element"]
node_dom["Browser DOM"]

node_caller -->|"registers elements"| node_install
node_install -->|"expands hotkeys"| node_expand
node_expand -->|"normalizes keys"| node_normalize
node_install -->|"inserts mappings"| node_trie
node_install -->|"adds listener"| node_dom
node_dom -->|"delivers keydown"| node_handler
node_handler -->|"serializes event"| node_serialize
node_serialize -->|"maps symbols"| node_macsymbols
node_serialize -->|"maps uppercase"| node_macuppercase
node_handler -->|"looks up key"| node_trie
node_handler -->|"records keypress"| node_tracker
node_handler -->|"dispatches match"| node_action
node_action -->|"fires event; focuses or clicks"| node_target
node_install -->|"removes mappings"| node_trie
node_install -->|"removes listener"| node_dom

click node_install "https://github.com/github/hotkey/blob/main/src/index.ts"
click node_handler "https://github.com/github/hotkey/blob/main/src/index.ts"
click node_trie "https://github.com/github/hotkey/blob/main/src/radix-trie.ts"
click node_tracker "https://github.com/github/hotkey/blob/main/src/sequence.ts"
click node_expand "https://github.com/github/hotkey/blob/main/src/utils.ts"
click node_serialize "https://github.com/github/hotkey/blob/main/src/hotkey.ts"
click node_normalize "https://github.com/github/hotkey/blob/main/src/hotkey.ts"
click node_macsymbols "https://github.com/github/hotkey/blob/main/src/macos-symbol-layer.ts"
click node_macuppercase "https://github.com/github/hotkey/blob/main/src/macos-uppercase-layer.ts"
click node_action "https://github.com/github/hotkey/blob/main/src/utils.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_install,node_handler,node_dom toneBlue
class node_trie,node_tracker,node_expand toneAmber
class node_action toneMint
class node_serialize,node_normalize,node_macsymbols,node_macuppercase toneRose
class node_caller,node_target toneIndigo
```

## Components

### Registration API

- [Install / uninstall](https://github.com/github/hotkey/blob/main/src/index.ts): `src/index.ts`
- [Keydown handler](https://github.com/github/hotkey/blob/main/src/index.ts): `src/index.ts`

### Key Matching

- [Hotkey trie](https://github.com/github/hotkey/blob/main/src/radix-trie.ts): `src/radix-trie.ts`
- [Sequence tracker](https://github.com/github/hotkey/blob/main/src/sequence.ts): `src/sequence.ts`
- [Alias expansion](https://github.com/github/hotkey/blob/main/src/utils.ts): `src/utils.ts`

### Dispatch and Actions

- [Action dispatch](https://github.com/github/hotkey/blob/main/src/utils.ts): `src/utils.ts`

### Key Normalization

- [Event serialization](https://github.com/github/hotkey/blob/main/src/hotkey.ts): `src/hotkey.ts`
- [Hotkey normalization](https://github.com/github/hotkey/blob/main/src/hotkey.ts): `src/hotkey.ts`
- [Mac symbol map](https://github.com/github/hotkey/blob/main/src/macos-symbol-layer.ts): `src/macos-symbol-layer.ts`
- [Mac uppercase map](https://github.com/github/hotkey/blob/main/src/macos-uppercase-layer.ts): `src/macos-uppercase-layer.ts`

### Other components

- **Integrating page**
- **Target element**
- **Browser DOM**

## Connections

- Integrating page → Install / uninstall: registers elements
- Install / uninstall → Alias expansion: expands hotkeys
- Alias expansion → Hotkey normalization: normalizes keys
- Install / uninstall → Hotkey trie: inserts mappings
- Install / uninstall → Browser DOM: adds listener
- Browser DOM → Keydown handler: delivers keydown
- Keydown handler → Event serialization: serializes event
- Event serialization → Mac symbol map: maps symbols
- Event serialization → Mac uppercase map: maps uppercase
- Keydown handler → Hotkey trie: looks up key
- Keydown handler → Sequence tracker: records keypress
- Keydown handler → Action dispatch: dispatches match
- Action dispatch → Target element: fires event; focuses or clicks
- Install / uninstall → Hotkey trie: removes mappings
- Install / uninstall → Browser DOM: removes listener