claude-code/packages/@ant/ink/docs/08-keybindings.md

Chapter 8: Keybinding System

The keybinding system provides configurable, context-aware keyboard shortcuts with chord sequence support.

Architecture

KeybindingSetup (loads config)
  └── KeybindingProvider (provides context)
        ├── useKeybinding(action, handler)
        ├── useKeybindings({ action: handler })
        ├── useKeybindingContext()
        └── useRegisterKeybindingContext(name, isActive)

KeybindingSetup

Loads and validates keybinding configuration at app startup.

import { KeybindingSetup } from '@anthropic/ink'

<KeybindingSetup
  loadBindings={() => parseUserKeybindings(configFile)}
  subscribeToChanges={(cb) => watchConfigFile(cb)}
  onWarnings={(warnings, isReload) => {
    warnings.forEach(w => console.warn(w.message))
  }}
>
  <App />
</KeybindingSetup>

Props

Prop	Type	Description
children	ReactNode	App tree
loadBindings	() => KeybindingsLoadResult	Load bindings from config
subscribeToChanges	(cb) => unsubscribe	Watch for config changes
initWatcher	() => void | Promise<void>	One-time setup (optional)
onWarnings	(warnings, isReload) => void	Validation warnings (optional)
onDebugLog	(message) => void	Debug logging (optional)

KeybindingsLoadResult

type KeybindingsLoadResult = {
  bindings: ParsedBinding[]
  warnings: KeybindingWarning[]
}

KeybindingWarning

type KeybindingWarning = {
  type: 'parse_error' | 'duplicate' | 'reserved' | 'invalid_context' | 'invalid_action'
  severity: 'error' | 'warning'
  message: string
  key?: string
  context?: string
  action?: string
  suggestion?: string
}

KeybindingProvider

Context provider that holds binding state and resolution logic. Automatically provided by KeybindingSetup.

useKeybinding

Register a handler for a keybinding action.

import { useKeybinding } from '@anthropic/ink'

function MyComponent() {
  useKeybinding('app:toggleTodos', () => {
    setShowTodos(prev => !prev)
  }, { context: 'Global' })

  // Return false to NOT consume the event (allow propagation)
  useKeybinding('scroll:lineDown', () => {
    if (!hasContent) return false  // Don't consume
    scrollBy(1)
  })
}

Signature

function useKeybinding(
  action: string,
  handler: () => void | false | Promise<void>,
  options?: { context?: string; isActive?: boolean }
): void

Handler Return Values

Return	Effect
undefined / void	Event consumed, stop propagation
false	Event NOT consumed, propagate to other handlers
Promise<void>	Async handler, treated as consumed

useKeybindings

Register multiple handlers in one hook (reduces useInput overhead).

import { useKeybindings } from '@anthropic/ink'

useKeybindings({
  'chat:submit': () => handleSubmit(),
  'chat:cancel': () => handleCancel(),
  'scroll:pageDown': () => {
    scrollBy(viewportHeight)
  },
  'scroll:lineDown': () => {
    if (!hasContent) return false
    scrollBy(1)
  },
}, { context: 'Chat' })

Keybinding Contexts

Contexts allow the same key to perform different actions depending on what's active.

// Register a context as active
import { useRegisterKeybindingContext } from '@anthropic/ink'

function ThemePicker({ isOpen }) {
  useRegisterKeybindingContext('ThemePicker', isOpen)

  // While open, 'ThemePicker' context bindings take precedence
  useKeybinding('picker:select', handleSelect, { context: 'ThemePicker' })

  return isOpen ? <PickerUI /> : null
}

Context resolution order:

1. Registered active contexts (most recent first)
2. The hook's own context parameter
3. 'Global' (always checked last)

Chord Sequences

Keybindings support multi-key sequences (chords):

"ctrl+k ctrl+s"  →  Save (press Ctrl+K, then Ctrl+S)
"ctrl+k ctrl+c"  →  Close (press Ctrl+K, then Ctrl+C)

When a chord prefix is pressed:

• result.type === 'chord_started' -- Show "Ctrl+K ..." pending indicator
• Next key completes or cancels the chord
• result.type === 'chord_cancelled' -- Invalid key, reset

KeybindingContext Hook

import { useKeybindingContext, useOptionalKeybindingContext } from '@anthropic/ink'

const ctx = useKeybindingContext()
// ctx.resolve(input, key, contexts)  → ResolveResult
// ctx.bindings                       → ParsedBinding[]
// ctx.pendingChord                   → ParsedKeystroke[] | null
// ctx.activeContexts                  → Set<string>
// ctx.getDisplayText(action, context) → string | undefined
// ctx.invokeAction(action)           → boolean
// ctx.registerHandler(registration)   → () => void  (unsubscribe)

// Returns null outside provider (no throw)
const optionalCtx = useOptionalKeybindingContext()

Parser Functions

Parse and format keybinding strings:

import {
  parseKeystroke,
  parseChord,
  keystrokeToString,
  chordToString,
  keystrokeToDisplayString,
  chordToDisplayString,
  parseBindings,
} from '@anthropic/ink'

parseKeystroke(str)

Parse a single keystroke string:

parseKeystroke('ctrl+shift+enter')
// → { key: 'enter', ctrl: true, alt: false, shift: true, meta: false, super: false }

parseChord(str)

Parse a chord (space-separated keystrokes):

parseChord('ctrl+k ctrl+s')
// → [{ key: 'k', ctrl: true, ... }, { key: 's', ctrl: true, ... }]

keystrokeToString(ks) / chordToString(chord)

Convert parsed keystroke/chord back to string.

keystrokeToDisplayString(ks) / chordToDisplayString(chord)

Convert to human-readable display string (platform-aware).

parseBindings(blocks)

Parse a keybinding configuration:

parseBindings([
  {
    context: 'Global',
    bindings: {
      'ctrl+s': 'app:save',
      'ctrl+k ctrl+s': 'app:saveAs',
    }
  }
])
// → ParsedBinding[]

Match Functions

import { getKeyName, matchesKeystroke, matchesBinding } from '@anthropic/ink'

getKeyName(input, key)

Get the canonical key name from raw input:

getKeyName('\x1b[A', { upArrow: true })  // 'up'

matchesKeystroke(input, key, target)

Check if raw input matches a parsed keystroke:

matchesKeystroke('s', { ctrl: true, shift: false }, { key: 's', ctrl: true })

matchesBinding(input, key, binding)

Check if raw input matches any keystroke in a binding's chord.

Resolver Functions

import { resolveKey, resolveKeyWithChordState, getBindingDisplayText } from '@anthropic/ink'

resolveKey(input, key, contexts, bindings)

Resolve input to a binding action:

const result = resolveKey('s', { ctrl: true, shift: false }, ['Global'], bindings)
// result.type: 'match' | 'none' | 'unbound'
// result.action: string (when type === 'match')

resolveKeyWithChordState(input, key, contexts, bindings, pendingChord)

Resolve with chord state:

const result = resolveKeyWithChordState('k', key, ['Global'], bindings, null)
// result.type: 'match' | 'none' | 'unbound' | 'chord_started' | 'chord_cancelled'
// result.pending: ParsedKeystroke[] (when type === 'chord_started')

getBindingDisplayText(action, context, bindings)

Get the display string for a binding:

getBindingDisplayText('app:save', 'Global', bindings)  // 'Ctrl+S'