react-kbd-shortcuts

A 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.

📺 View Live Demo

✨ 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

Installation

``bash
npm install react-kbd-shortcuts


or

`jsx
import { Key, KeyCombo, useKeyCombo } from "react-kbd-shortcuts";

// Individual key
Ctrl

// Key combination


// With symbols


// Hook for logic
const keys = useKeyCombo("ctrl+alt+delete");
`

Usage Examples

$3

`jsx
import { Key } from "react-kbd-shortcuts";

// Basic usage
Ctrl

// With HTML props
Enter

// Custom rendering
(
{content}
)}>
Escape

`

$3

`jsx
import { KeyCombo } from "react-kbd-shortcuts";

// Basic usage


// With HTML props


// Custom rendering
combo="command option S"
render={(keys) => (


`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 (


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) => (


// 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 names

Returns: 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, volumemute

Examples

$3

`jsx
// Save


// Copy/Paste



// Undo/Redo



// Search


// Command palette

`

$3

`jsx
function DocumentationExample() {
return (


`jsx
function InteractiveShortcut({ combo, onTrigger }) {
return (
combo={combo}
className="shortcut-button"
onClick={onTrigger}
role="button"
tabIndex={0}
render={(keys) => (


`bash


Build once

`
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

The sandbox imports from dist/`, so the library auto-rebuilds when you edit source files.