A headless React library for parsing and rendering keyboard shortcuts from natural language input
npm install react-kbd-shortcutsA headless React library for parsing and rendering keyboard shortcuts from natural language input. Easily convert phrases like "ctrl+shift+K" or "command option S" into normalized key arrays, and render them with full control over styling and markup. Includes logic-only hooks and components for maximum flexibility - ideal for building custom shortcut UIs, documentation, or interactive help overlays.
⨠Features:
- Headless: No built-in styles - render shortcuts your way
- Natural input: Parse human-friendly shortcut strings
- OS-aware: Mac, Windows, and Linux specific key names
- Symbol mode: Unicode symbols (ā, ā, ā„) or text labels
- Render props: Complete control over markup and styling
- TypeScript: Full type safety with exported types
- React hooks & components: Use logic in any React app
``bash`
npm install react-kbd-shortcutsor
npm install react-kbd-shortcutsor
yarn add react-kbd-shortcuts
`jsx
import { Key, KeyCombo, useKeyCombo } from "react-kbd-shortcuts";
// Individual key
// Key combination
// With symbols
// Hook for logic
const keys = useKeyCombo("ctrl+alt+delete");
`
`jsx
import { Key } from "react-kbd-shortcuts";
// Basic usage
// With HTML props
// Custom rendering
)}>
Escape
`
`jsx
import { KeyCombo } from "react-kbd-shortcuts";
// Basic usage
// With HTML props
// Custom rendering
render={(keys) => (
$3
`jsx
import { useKeyCombo } from "react-kbd-shortcuts";function MyComponent() {
// Basic usage
const keys = useKeyCombo("ctrl alt delete");
// With symbols
const symbols = useKeyCombo("cmd+shift+p", true);
// OS-specific
const macKeys = useKeyCombo("ctrl+cmd+s", false, "mac");
return (
Keys: {keys.join(" + ")}
Symbols: {symbols.join(" ")}
Mac: {macKeys.join(" + ")}
);
}
`Advanced Features
$3
Use the
os prop to render platform-specific key names:`jsx
import { KeyCombo, type SupportedOS } from "react-kbd-shortcuts";// Mac: "Control + Cmd + S"
// Windows: "Ctrl + Win + S"
// Linux: "Ctrl + Super + S"
// Auto-detect (example)
const os: SupportedOS = navigator.platform.includes('Mac') ? 'mac' : 'windows';
`$3
Pass
useSymbols={true} to render Unicode symbols instead of text:`jsx
// Text mode (default): "Ctrl + Shift + K"
// Symbol mode: "ā + ā§ + K"
// OS-specific symbols
// "ā + ā"
// "Ctrl + ā"
// "Ctrl + ā"
`$3
Both
Key and KeyCombo support render props for complete control:`jsx
// Key with custom rendering
(
{content}
)}>
Ctrl
// KeyCombo with custom rendering
combo="cmd+shift+p"
render={(keys) => (
{keys.map((key, i) => (
{key}
{i < keys.length - 1 && +}
))}
)}
/>// Combining with OS and symbols
combo="ctrl+cmd+s"
os="mac"
useSymbols
render={(keys) => (
{keys.join('')}
)}
/>
`$3
Full TypeScript support with exported types:
`tsx
import {
Key,
KeyCombo,
useKeyCombo,
type SupportedOS,
type KeyProps,
type KeyComboProps,
} from "react-kbd-shortcuts";interface ShortcutProps {
combo: string;
os: SupportedOS;
}
function Shortcut({ combo, os }: ShortcutProps) {
return ;
}
`Available symbols:
- Ctrl ā ā
- Meta (Command/Win) ā ā
- Alt (Option) ā ā„
- Shift ā ā§
- Enter ā āµ
- Escape ā ā
- Tab ā ā„
- Backspace ā ā«
- Delete ā ā¦
- CapsLock ā āŖ
- Arrow keys ā ā ā ā ā
- PageUp/Down ā ā ā
- Home/End ā ā ā
API Reference
$3
####
Renders a single keyboard key.
Props:
-
children - The key content to display
- render? - Custom render function (content) => ReactNode
- ...props - Any standard HTML attributes (className, onClick, etc.)####
Renders a keyboard shortcut combination.
Props:
-
combo? - Shortcut string (e.g., "ctrl+shift+k")
- useSymbols? - Use Unicode symbols instead of text
- os? - Target OS: "mac" | "windows" | "linux"
- render? - Custom render function (keys: string[]) => ReactNode
- ...props - Any standard HTML attributes$3
####
useKeyCombo(input, useSymbols?, os?)Parses shortcut string and returns key array.
Parameters:
-
input - Shortcut string to parse
- useSymbols? - Return symbols instead of text
- os? - Target OS for key namesReturns:
string[] - Array of parsed key names$3
####
parseKeyCombo(input, useSymbols?, os?)Direct parser function (same as hook but not React-specific).
$3
`tsx
type SupportedOS = "mac" | "windows" | "linux";interface KeyProps {
children?: ReactNode;
render?: (content: ReactNode) => ReactNode;
[key: string]: any;
}
interface KeyComboProps {
combo?: string;
render?: (keys: string[]) => ReactNode;
useSymbols?: boolean;
os?: SupportedOS | null;
[key: string]: any;
}
`Supported Keys
$3
-
ctrl, control ā Ctrl (Control on Mac)
- cmd, command, win ā Cmd (Win on Windows, Super on Linux)
- alt, option ā Alt (Option on Mac)
- shift ā Shift$3
-
up, down, left, right, uparrow, downarrow, leftarrow, rightarrow ā Arrow keys
- home, end
- pageup, pagedown, pgup, pgdn ā Page Up/Down$3
-
enter, tab, space
- backspace, delete, del
- esc, escape$3
-
f1 through f12 ā F1-F12$3
-
comma, period, slash, backslash
- semicolon, quote
- bracketleft, bracketright
- equal, plus, minus$3
-
num0 through num9 ā Numpad digits
- nummultiply, numadd, numsubtract, numdecimal, numdivide ā Numpad operators$3
-
capslock, caps ā Caps Lock
- numlock, num ā Num Lock
- scrolllock, scroll ā Scroll Lock
- insert, ins
- pause
- printscreen, prtsc ā Print Screen$3
-
volumeup, volumedown, volumemuteExamples
$3
`jsx
// Save
// Copy/Paste
// Undo/Redo
// Search
// Command palette
`$3
`jsx
function DocumentationExample() {
return (
Press to open search, or{" "}
to open commands.
);
}
`$3
`jsx
function InteractiveShortcut({ combo, onTrigger }) {
return (
combo={combo}
className="shortcut-button"
onClick={onTrigger}
role="button"
tabIndex={0}
render={(keys) => (
{keys.map((key, i) => (
{key}
))}
)}
/>
);
}
`Development
$3
`bash
Build once
npm run buildBuild and watch for changes
npm run dev
`$3
`
react-kbd-shortcuts/
āāā src/
ā āāā components/ # React components
ā āāā hooks/ # React hooks
ā āāā utils/ # Parser utilities
ā āāā index.js # Main entry
āāā dist/ # Built ESM output (gitignored)
āāā index.d.ts # TypeScript definitions
āāā rollup.config.mjs # Build configuration
`$3
Use the sandbox example to test changes during development:
`bash
Build the library in watch mode
npm run devIn another terminal, run the sandbox
cd examples/sandbox
npm run dev
`The sandbox imports from
dist/`, so the library auto-rebuilds when you edit source files.