KeyboardShortcut

Usage

Basic Example

Display a simple keyboard shortcut:

<KeyboardShortcut keys={["command", "k"]} label="Open command palette" />

Multiple Keys

Display shortcuts with multiple modifier keys and combinations:

<KeyboardShortcut keys={["command", "shift", "p"]} label="Command palette" />
<KeyboardShortcut keys={["ctrl", "alt", "delete"]} label="Task manager" />
<KeyboardShortcut keys={["shift", "enter"]} label="New line" />

Platform-Specific Overrides

Provide different key combinations for different platforms. The component automatically detects the user's platform:

<KeyboardShortcut
  keys={["command", "k"]}
  mac={["command", "k"]}
  win={["ctrl", "k"]}
  linux={["ctrl", "k"]}
  label="Open command palette"
/>

Key Press Animation

Enable the listen prop to show visual feedback when the shortcut is pressed. Try pressing the shortcut below:

<KeyboardShortcut
  keys={["shift", "a"]}
  listen
  label="Example with animation"
/>

Provider

Use KeyboardShortcutProvider to configure global defaults for all shortcuts:

Display Modes

The display prop controls how modifier keys are rendered. Use "symbol" for icons or "text" for labels:

// Symbol display (default)
<KeyboardShortcutProvider display="symbol">
  <KeyboardShortcut keys={["command", "shift", "k"]} label="Symbol display" />
</KeyboardShortcutProvider>

// Text display
<KeyboardShortcutProvider display="text">
  <KeyboardShortcut keys={["command", "shift", "k"]} label="Text display" />
</KeyboardShortcutProvider>

Platform Override

Force a specific platform instead of auto-detection with the platform prop:

<KeyboardShortcutProvider platform="mac">
  <KeyboardShortcut
    keys={["command", "c"]}
    mac={["command", "c"]}
    win={["ctrl", "c"]}
    label="Copy"
  />
</KeyboardShortcutProvider>

Global Listen

Enable key press animation for all shortcuts within the provider with the listen prop:

<KeyboardShortcutProvider listen>
  <KeyboardShortcut keys={["command", "k"]} label="All shortcuts animate" />
  <KeyboardShortcut keys={["command", "j"]} label="Including this one" />
</KeyboardShortcutProvider>

matchShortcut Utility

The matchShortcut function helps you handle keyboard events by checking if they match a key combination:

import { matchShortcut } from "@228-co/reef/components";

function handleKeyDown(event: KeyboardEvent) {
  if (matchShortcut(event, ["command", "k"])) {
    event.preventDefault();
    openCommandPalette();
  }
  
  if (matchShortcut(event, ["ctrl", "shift", "p"])) {
    event.preventDefault();
    openQuickOpen();
  }
}

// Add to your component
window.addEventListener("keydown", handleKeyDown);

The function handles modifier key normalization automatically, so you can use the same key names as in the component props.

SmartString Integration

Keyboard shortcuts can be embedded in SmartStrings using the reef/kbd tag:

import type { SmartString } from "@228-co/reef/smart-string";

const content: SmartString = [
  "Press ",
  { _tag: "reef/kbd", keys: ["command", "k"], label: "Open command palette" },
  " to open the command palette.",
];

<Text>{content}</Text>

See the

Component Props

Provider Props

Supported Keys

Keys are case-insensitive. The Key type enforces valid key strings at compile time.

Modifier Keys

Special Keys

Standard Keys

Letters (a-z) display as uppercase. Numbers (0-9) display as-is. Invalid keys render as-is without error.

Styling

The component uses theme tokens for consistent styling. You can customize the appearance by overriding these tokens in your theme:

// Theme tokens used by KeyboardShortcut
themeDetails: {
  kbdBackground: themeColors.neutral300,  // Background color
  kbdForeground: themeColors.primary500,  // Text color
  kbdPaddingInline: themeSizing.spaceXS,  // Horizontal padding
  kbdPaddingBlock: "...",                 // Vertical padding
  kbdBorderRadius: "...",                 // Corner radius
  kbdFontSize: themeSizing.font0,         // Font size
  kbdGap: "...",                          // Gap between keys
}

Accessibility

The label prop is required and sets the aria-label attribute, ensuring screen readers can announce the shortcut's purpose.

Each key is rendered as a <kbd> element, which is the semantic HTML element for keyboard input.