react-hotkey-display

The visual display layer for the React hotkey ecosystem.

Live Demo · Install · Components

Features

• Automatic OS detection — Mod+S renders as ⌘S on Mac, Ctrl + S on Windows
• Mac symbols — ⌘ ⇧ ⌥ ⌃ ⏎ ⌫ ⇥ ⎋ and more
• 5 components — <Kbd>, <Hotkey>, <ShortcutHint>, <ShortcutCheatsheet>, <ShortcutPalette>
• Command Palette — ⌘K-style searchable command list with keyboard navigation
• Cheatsheet Overlay — grouped, searchable shortcut reference
• 3 size variants — sm, md, lg
• 4 visual themes — elevated (macOS-style), subtle (GitHub-style), flat, outlined
• Unstyled mode — unstyled prop strips all CSS classes, keeps semantic HTML
• Accessible — semantic <kbd> elements, ARIA labels, combobox pattern, screen reader friendly
• SSR-safe — works with Next.js via useSyncExternalStore
• Works with any hotkey library — normalizeCombo() converts TanStack, react-hotkeys-hook, and tinykeys formats
• Tiny — ~3.8KB JS gzipped, modular CSS

Install

npm install react-hotkey-display

Quick Start

import { Hotkey } from 'react-hotkey-display';
import 'react-hotkey-display/styles.css';

function App() {
  return (
    <div>
      <p>Save: <Hotkey combo="Mod+S" /></p>
      <p>Search: <Hotkey combo="Mod+K" /></p>
      <p>Undo: <Hotkey combo="Mod+Z" /></p>
    </div>
  );
}

On Mac: ⌘S, ⌘K, ⌘Z On Windows: Ctrl + S, Ctrl + K, Ctrl + Z

Components

<Hotkey>

Displays a keyboard shortcut with OS-aware formatting.

<Hotkey combo="Mod+Shift+P" />           // ⇧⌘P (Mac) or Ctrl + Shift + P (Windows)
<Hotkey combo="Mod+K" variant="subtle" /> // GitHub-style
<Hotkey combo="G G" />                    // G → G (sequence support)
<Hotkey combo="Mod+K" size="sm" />        // Small variant
<Hotkey combo="Mod+K" unstyled />         // Semantic HTML, no CSS classes

Prop	Type	Default	Description
combo	string	required	Key combo, e.g. "Mod+Shift+K". Space = sequence separator.
platform	'mac' | 'windows' | 'linux'	auto-detect	Override OS detection
variant	'elevated' | 'subtle' | 'flat' | 'outlined'	'elevated'	Visual style
size	'sm' | 'md' | 'lg'	'md'	Size variant
unstyled	boolean	false	Omit all hkd-* CSS classes
separator	string	"" (Mac) / " + " (Win)	Key separator
className	string	—	Additional CSS class

<Kbd>

Single key display.

<Kbd>⌘</Kbd>
<Kbd variant="subtle">Ctrl</Kbd>
<Kbd size="lg">Enter</Kbd>

<ShortcutHint>

Action label paired with its keyboard shortcut.

<ShortcutHint action="Save" combo="Mod+S" />
// → "Save  ⌘S" (Mac) / "Save  Ctrl+S" (Win)

<ShortcutCheatsheet>

Searchable keyboard shortcut reference overlay using the native <dialog> element.

import { ShortcutCheatsheet, ShortcutProvider } from 'react-hotkey-display';
import 'react-hotkey-display/styles.css';
import 'react-hotkey-display/cheatsheet.css';

const shortcuts = [
  { id: 'save', combo: 'Mod+S', description: 'Save', category: 'File' },
  { id: 'find', combo: 'Mod+F', description: 'Find', category: 'Edit' },
];

function App() {
  const [open, setOpen] = useState(false);

  return (
    <ShortcutProvider shortcuts={shortcuts}>
      <button onClick={() => setOpen(true)}>Show Shortcuts</button>
      <ShortcutCheatsheet open={open} onOpenChange={setOpen} />
    </ShortcutProvider>
  );
}

Shortcuts can be passed directly as a prop or read from the ShortcutProvider context.

<ShortcutPalette>

⌘K-style command palette with keyboard navigation (Arrow keys + Enter).

import { ShortcutPalette, ShortcutProvider } from 'react-hotkey-display';
import 'react-hotkey-display/styles.css';
import 'react-hotkey-display/palette.css';

const shortcuts = [
  { id: 'save', combo: 'Mod+S', description: 'Save', category: 'File', action: () => save() },
  { id: 'find', combo: 'Mod+F', description: 'Find', category: 'Edit', action: () => openFind() },
];

function App() {
  const [open, setOpen] = useState(false);

  return (
    <ShortcutProvider shortcuts={shortcuts}>
      <ShortcutPalette
        open={open}
        onOpenChange={setOpen}
        onSelect={(shortcut) => shortcut.action?.()}
      />
    </ShortcutProvider>
  );
}

<ShortcutProvider>

Context provider for sharing shortcuts between components. Not required — all components accept a shortcuts prop directly.

<ShortcutProvider shortcuts={shortcuts}>
  <App />
</ShortcutProvider>

Hooks:

• useShortcuts() — read all registered shortcuts
• useRegisterShortcut(entry) — dynamically register a shortcut (auto-cleanup on unmount)

Integration with Hotkey Libraries

normalizeCombo() converts combo formats from popular libraries to our format:

import { normalizeCombo } from 'react-hotkey-display';

// tinykeys format
normalizeCombo('$mod+KeyK')     // → "Mod+K"
normalizeCombo('$mod+Digit1')   // → "Mod+1"
normalizeCombo('ArrowUp')       // → "Up"

// TanStack format
normalizeCombo('$mod+KeyS')     // → "Mod+S"

// react-hotkeys-hook format (mostly compatible already)
normalizeCombo('meta+k')        // → "Mod+k"

The Mod Key

Use Mod as a platform-agnostic modifier:

• Mac: renders as ⌘ (Command)
• Windows/Linux: renders as Ctrl

Supported Keys

Input	Mac	Windows
Mod	⌘	Ctrl
Ctrl	⌃	Ctrl
Shift	⇧	Shift
Alt / Option	⌥	Alt
Enter	⏎	Enter
Backspace	⌫	Backspace
Delete	⌦	Delete
Tab	⇥	Tab
Escape	⎋	Esc
Space	␣	Space
Up/Down/Left/Right	↑↓←→	↑↓←→
F1–F12	F1–F12	F1–F12

Theming

Customize via CSS Custom Properties:

:root {
  --hkd-font: 'Inter', sans-serif;
  --hkd-font-size: 0.75rem;
  --hkd-radius: 6px;
  --hkd-color: #1a1a1a;
  --hkd-bg: #f5f5f5;
  --hkd-border: #e5e5e5;
}

All CSS classes use the hkd- prefix. Dark mode is supported via prefers-color-scheme.

Use unstyled prop on any component to strip all hkd-* classes while keeping semantic HTML — perfect for building your own styles on top.

Utility Functions

import { formatCombo, normalizeCombo, parseCombo, detectPlatform } from 'react-hotkey-display';

const platform = detectPlatform(); // 'mac' | 'windows' | 'linux'
const keys = formatCombo('Mod+Shift+K', platform); // ['⌘', '⇧', 'K'] on Mac
const normalized = normalizeCombo('$mod+KeyK'); // 'Mod+K'

Function	Description
formatCombo(combo, platform)	Format a full combo string into display keys
formatKey(key, platform)	Format a single key for a given platform
parseCombo(combo)	Parse "Mod+Shift+K" into ["Mod", "Shift", "K"]
normalizeCombo(combo)	Normalize tinykeys/TanStack/react-hotkeys-hook format
getAriaLabel(key)	Screen reader label for a key symbol
getComboAriaLabel(keys)	Full screen reader label for formatted keys
detectPlatform()	Detect user's OS
usePlatform(override?)	SSR-safe React hook for platform detection

SSR / Next.js

The usePlatform hook uses useSyncExternalStore for hydration-safe platform detection. On the server, it renders as "windows". After hydration, it updates to the detected platform.

<Hotkey combo="Mod+S" platform="mac" /> // Skip detection entirely

Browser Support

Works in all modern browsers. <dialog> element requires Safari 15.4+ (March 2022).

License

MIT