Keybound

Desktop-grade keyboard interactions for modern React applications.

🌐keybound.eggwite.moe

Overview · Installation · Quick Start · Frameworks · Documentation · Contributing

---

Overview

Desktop-grade keyboard ergonomics for React apps:

• Mnemonics: Platform-aware accelerators via & syntax (<button>&File</button>) with semantic underlines (Alt+F on Windows/Linux, ⌘F on macOS).
• Hotkeys: Declarative element bindings (<input hotkey="mod+k" />).
• Modal Scoping: Blocks background shortcuts when dialogs, sheets, or palettes are active.
• Overlay Hints: Floating keycap badges on demand (<KeyboundOverlay />).
• Hooks API: useMnemonic and useHotkey for dynamic labels and i18n without a build step.
• Tiny Footprint: ~7.9 KB gzipped runtime. React peer dependencies only. Zero runtime dependencies.
• SSR Safe: Listeners attach in client effects; Next.js, Vite, and Remix compatible.

---

Installation

npm install react-keybound

---

Quick Start

1. Wrap Your App

import { KeyboundProvider } from 'react-keybound';
import type {} from 'react-keybound/jsx';

export function App({ children }: { children: React.ReactNode }) {
  // mnemonicModifier="auto" defaults to Alt on Windows/Linux and ⌘ (mod) on macOS/iPadOS
  return <KeyboundProvider>{children}</KeyboundProvider>;
}

2. Add Mnemonics & Hotkeys

With the compiler enabled:

export function Toolbar() {
  return (
    <nav>
      {/* Alt+F / ⌘F triggers File, Alt+E / ⌘E triggers Edit */}
      <button onClick={() => openMenu('file')}>&File</button>
      <button onClick={() => openMenu('edit')}>&Edit</button>

      {/* Mod+K (⌘K on macOS, Ctrl+K on Windows/Linux) focuses search */}
      <input hotkey="mod+k" placeholder="Search (⌘K)..." />
    </nav>
  );
}

Syntax:

• &Save → Save (Alt+S on Windows/Linux, ⌘S on macOS)
• E&xport → Export (Alt+X on Windows/Linux, ⌘X on macOS)
• Save && &Close → Save & Close (Alt+C / ⌘C, && for literal &)

Cross-Platform Modifiers & macOS Quirks

By default, <KeyboundProvider> sets mnemonicModifier="auto":

• Windows & Linux: Uses Alt (Alt+S).
• macOS & iPadOS: Uses mod / Command (⌘S).

Why not Option on macOS?

On Apple hardware, the Option (⌥) key is an alternate character and dead-key composer. Pressing Option+S outputs ß, and Option+E produces Dead. Under Keybound's pure semantic matching (KeyboardEvent.key), these glyphs do not match ASCII letters. Using mod (⌘) keeps mnemonics accessible as clean semantic characters.

Granular Platform Mapping

If you want to avoid browser-reserved shortcuts on Mac (e.g. ⌘W or ⌘T), you can map mac to Control (⌃), which is completely free from browser intercepts:

<KeyboundProvider
  mnemonicModifier={{
    mac: 'ctrl', // ⌃S on macOS
    windows: 'alt', // Alt+S on Windows
    linux: 'alt', // Alt+S on Linux
  }}
>
  {children}
</KeyboundProvider>

3. Hooks (Compiler-Free)

For dynamic strings or runtime translations:

import { useMnemonic, useHotkey } from 'react-keybound';

function ActionButton({ text, onAction }: { text: string; onAction: () => void }) {
  const { label, triggerProps } = useMnemonic<HTMLButtonElement>(text, { onAction });
  return <button {...triggerProps}>{label}</button>;
}

function GlobalSearch() {
  const { triggerProps } = useHotkey<HTMLInputElement>('mod+k');
  return <input {...triggerProps} placeholder="Search..." />;
}

---

Framework Integration

Next.js (next.config.ts)

import { withKeybound } from 'react-keybound/next';

export default withKeybound(
  {},
  {
    components: ['Button', 'Link'],
  },
);

Vite (vite.config.ts)

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import keybound from 'react-keybound/vite';

export default defineConfig({
  plugins: [keybound(), react()],
});

---

Documentation

• Interactive Studio
• Documentation & Guides
• Examples
• Behavioral Specification
• Agent Guide

---

Contributing

1. Clone the repository:

   git clone https://github.com/Eggwite/keybound.git
   cd keybound

2. Install dependencies:

   npm ci

3. Start the dev playground:

   npm run dev

4. Verify changes:

   npm run check
   npm run format:check

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and AGENTS.md.

---

License

MIT © Eggwite