Keyboard Shortcuts

modern-cmdk includes a built-in keyboard shortcut registry. Shortcuts are registered alongside items, displayed via <Command.Shortcut>, and active even when the command palette is closed.

Registering Shortcuts

Add the shortcut prop to any <Command.Item>:

'use client';

import { Command } from 'modern-cmdk/react';

function ShortcutPalette() {
  return (
    <Command>
      <Command.Input placeholder="Search..." />
      <Command.List>
        <Command.Item value="copy" shortcut="Mod+C" onSelect={() => navigator.clipboard.writeText('Hello')}>
          Copy
          <Command.Shortcut shortcut="Mod+C" />
        </Command.Item>
        <Command.Item value="paste" shortcut="Mod+V" onSelect={() => console.log('paste')}>
          Paste
          <Command.Shortcut shortcut="Mod+V" />
        </Command.Item>
        <Command.Item value="save" shortcut="Mod+S" onSelect={() => console.log('save')}>
          Save
          <Command.Shortcut shortcut="Mod+S" />
        </Command.Item>
        <Command.Item value="find" shortcut="Mod+Shift+F" onSelect={() => console.log('find')}>
          Find in Files
          <Command.Shortcut shortcut="Mod+Shift+F" />
        </Command.Item>
      </Command.List>
    </Command>
  );
}

<Command.Shortcut> Display Component

<Command.Shortcut> renders a platform-aware keyboard shortcut badge. On macOS it shows symbols like Cmd, on Windows/Linux it shows Ctrl:

import { Command } from 'modern-cmdk/react';

export function ShortcutBadges() {
  return (
    <>
      {/* macOS renders: ⌘C */}
      {/* Windows/Linux renders: Ctrl+C */}
      <Command.Shortcut shortcut="Mod+C" />

      {/* macOS renders: ⌘⇧F */}
      {/* Windows/Linux renders: Ctrl+Shift+F */}
      <Command.Shortcut shortcut="Mod+Shift+F" />
    </>
  );
}

The component renders with [data-command-shortcut] for styling:

[data-command-shortcut] {
  display: inline-flex;
  gap: 4px;
  font-family: var(--font-mono);
  font-size: 0.75rem;
  color: var(--color-text-muted);
}

[data-command-shortcut] kbd {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-width: 1.5rem;
  height: 1.5rem;
  padding-inline: 0.375rem;
  border-radius: 4px;
  border: 1px solid var(--color-border);
  background: var(--color-surface-2);
}

Platform-Aware Mod Key

The Mod modifier is a cross-platform alias:

Platform	Mod resolves to
macOS	Cmd (Command)
Windows	Ctrl
Linux	Ctrl

This means Mod+K registers as Cmd+K on Mac and Ctrl+K on Windows/Linux. Users see the correct key for their platform.

Shortcut Syntax

Shortcuts use a +-separated modifier and key format:

Modifier+Modifier+Key

Supported Modifiers

Modifier	Description
Mod	Platform-aware: Cmd on Mac, Ctrl elsewhere
Ctrl	Control key (explicit)
Shift	Shift key
Alt	Alt key (Option on Mac)
Meta	Meta key (Cmd on Mac, Win on Windows)

Examples

Shortcut String	macOS	Windows
Mod+K	Cmd+K	Ctrl+K
Mod+Shift+P	Cmd+Shift+P	Ctrl+Shift+P
Alt+Enter	Option+Enter	Alt+Enter
Ctrl+Shift+F	Ctrl+Shift+F	Ctrl+Shift+F

Utility Functions

parseShortcut(shortcut)

Parses a shortcut string into a structured ParsedShortcut object. It splits on +, resolves modifier aliases such as Mod, and normalizes the key:

import { parseShortcut } from 'modern-cmdk';

const parsed = parseShortcut('Mod+Shift+K');
// {
//   key: 'k',
//   meta: false,
//   ctrl: true,
//   shift: true,
//   alt: false,
//   raw: 'Mod+Shift+K',
//   normalized: 'ctrl+shift+k'  // 'meta+shift+k' on macOS
// }

formatShortcut(parsed)

Formats a parsed shortcut (the result of parseShortcut) into a human-readable display string using the symbols for the current platform:

import { formatShortcut, parseShortcut } from 'modern-cmdk';

formatShortcut(parseShortcut('Mod+Shift+K'));
// macOS: '⌘⇧K'
// Windows/Linux: 'Ctrl+Shift+K'

detectConflicts(shortcuts)

Detects conflicting keyboard shortcuts by grouping shortcuts by normalized form:

import { parseShortcut, detectConflicts } from 'modern-cmdk';

const shortcuts = [
  parseShortcut('Mod+C'),
  parseShortcut('Mod+C'),   // conflict!
  parseShortcut('Mod+V'),
];

const conflicts = detectConflicts(shortcuts);
// ReadonlyMap {
//   'ctrl+c' => [ParsedShortcut, ParsedShortcut],  // 'meta+c' on macOS
// }

TIP

detectConflicts groups shortcuts by their normalized form internally, then filters for groups with more than one entry. This is O(n) and runs during registration, not on every keystroke.

ARIA Integration

Items with shortcuts automatically receive aria-keyshortcuts for screen reader discoverability:

<!-- Rendered HTML -->
<div role="option" aria-keyshortcuts="Mod+C" data-command-item data-value="copy">
  Copy
  <kbd data-command-shortcut>⌘C</kbd>
</div>

WARNING

Avoid registering shortcuts that conflict with browser defaults (e.g., Ctrl+T, Ctrl+W, Ctrl+N). These cannot be reliably intercepted and will confuse users.