@gentleduck/vim

Keyboard command engine for React.

Bind hotkeys, record key sequences, and handle platform-aware modifier keys. Framework-agnostic core with React hooks included.

Why

• Multi-step key sequences (g then d) with configurable timeout
• Key recording for settings UIs where users customize their bindings
• Platform-aware Mod key: resolves to Cmd on macOS, Ctrl everywhere else

Quick start

npm install @gentleduck/vim

import { KeyProvider, useKeyBind } from '@gentleduck/vim/react'

function App() {
  useKeyBind('ctrl+k', () => console.log('open palette'), {
    preventDefault: true,
  })

  return <div>Press Ctrl+K</div>
}

export default function Root() {
  return (
    <KeyProvider>
      <App />
    </KeyProvider>
  )
}

Features

• Key parsing -- parse, normalize, and validate binding strings (Mod+Shift+S to structured descriptors)
• Sequences -- multi-step key chains with timeout and progress tracking
• Recording -- capture key combinations from user input for rebinding UIs
• React hooks -- useKeyBind, useKeySequence, useKeyRecorder, useKeyCommands
• Platform detection -- auto-detect macOS/Windows/Linux and resolve modifier labels
• Conflict detection -- warn, error, or silently replace duplicate bindings
• Per-binding options -- preventDefault, stopPropagation, ignoreInputs, requireReset

Modules

Each module is a separate subpath export and can be used independently:

| Module | Import | Purpose | |--------|--------|---------| | platform | @gentleduck/vim/platform | OS detection, Mod resolution | | parser | @gentleduck/vim/parser | Parse/normalize/validate bindings | | matcher | @gentleduck/vim/matcher | Match keyboard events | | format | @gentleduck/vim/format | Platform-aware display formatting | | command | @gentleduck/vim/command | Registry and key handler | | sequence | @gentleduck/vim/sequence | Multi-key sequence matching | | recorder | @gentleduck/vim/recorder | Key combination recording | | react | @gentleduck/vim/react | React context, hooks |

Bundle

• Zero runtime dependencies (React is a peer dep)
• Tree-shakeable subpath exports
• "sideEffects": false

Docs

gentleduck.org

License

MIT