Shortcut

Renders a keyboard shortcut as key caps. Modifier keys are spelled to match the reader's platform.

import { Shortcut } from 'neba';

<Shortcut keys="Mod+K" />
<Shortcut keys="Ctrl+Alt+Delete" os="windows" />
<Shortcut keys={['Mod', '+']} />;

Props

Prop	Type	Default	Description
keys *	string | string[]	—	The keys. A string is split on `+`: 'Mod+Shift+P'. The array form is for a shortcut whose key is itself a plus
os	'auto' | 'mac' | 'windows' | 'linux'	'auto'	Which keyboard to name the modifiers for. `auto` asks the browser; the three explicit values are for pages that have to name a platform rather than the reader's
separator	ReactNode	—	What goes between two keys. Omit it for the platform's own convention: a `+` off a Mac, and nothing at all on one
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the key cap. `outline` is the default: a key cap is a hairline box, which is what it has looked like in every manual ever printed
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale of the caps. One step below the control of the same size, exactly as a Chip is
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	Semantic colour role. `secondary` by default, because a key cap is chrome rather than an action
densityshared	'default' | 'compact'	'compact'	Horizontal padding of the caps only. `compact` by default, because a cap sits inside a line of text
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. This is a picture of a key, not a key: which is exactly why raising it is tempting and wrong

MenuItem's shortcut prop is the slot this component was written for.

<MenuItem shortcut={<Shortcut keys="Mod+E" />}>Rename</MenuItem>

Examples

keys

A string is split on +. The array form is only needed when a key is itself a plus. Single-character tokens are capitalised to match what is printed on the cap, and an unrecognised token is drawn exactly as written.

import { Shortcut } from 'neba';

const examples: { label: string; keys: string | string[] }[] = [
  { label: 'A single letter', keys: 'K' },
  { label: 'A named key', keys: 'Escape' },
  { label: 'Arrows, on every platform', keys: ['ArrowUp', 'ArrowDown'] },
  { label: 'A key that is itself a plus', keys: ['Mod', '+'] },
  { label: 'Three modifiers', keys: 'Mod+Alt+Shift+Delete' },
  { label: 'A function key', keys: 'F12' }
];

export default function ShortcutKeys() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      {examples.map((example) => (
        <div
          key={example.label}
          className="flex items-center justify-between gap-4 text-[0.8125rem]"
        >
          <span>{example.label}</span>
          <Shortcut keys={example.keys} />
        </div>
      ))}
    </div>
  );
}

os and Mod

Mod is the token for "the platform's primary modifier": Command (⌘) on macOS, Control everywhere else. Unlike the other tokens, which only change spelling, Mod changes which key it names.

os defaults to auto, which asks the browser for the current platform. Name mac, windows or linux for documentation that describes a specific platform.

The same strings are what the library binds: shortcut on CommandPalette and shortcuts on TextField, NumberField and Combobox all read this vocabulary. So do the aliases: Cmd, Command, Meta and Win are one key, and Esc, Return, Opt and Up are spellings of Escape, Enter, Alt and ArrowUp. A key cap and the key that fires it are the same string.

import { Shortcut } from 'neba';

/**
 * The same three shortcuts, named for three keyboards. `Mod` is the token that
 * changes meaning rather than spelling: Command on a Mac, Control everywhere
 * else — which is the whole reason writing `Ctrl` and hoping is wrong.
 */
export default function ShortcutPlatforms() {
  return (
    <div className="grid grid-cols-[auto_1fr_1fr_1fr] items-center gap-x-6 gap-y-3 text-[0.8125rem]">
      <span />
      <span className="text-[0.75rem] text-(--vp-c-text-3)">macOS</span>
      <span className="text-[0.75rem] text-(--vp-c-text-3)">Windows</span>
      <span className="text-[0.75rem] text-(--vp-c-text-3)">Linux</span>

      <span>Save</span>
      <Shortcut os="mac" keys="Mod+S" />
      <Shortcut os="windows" keys="Mod+S" />
      <Shortcut os="linux" keys="Mod+S" />

      <span>Search</span>
      <Shortcut os="mac" keys="Mod+Shift+F" />
      <Shortcut os="windows" keys="Mod+Shift+F" />
      <Shortcut os="linux" keys="Mod+Shift+F" />

      <span>Lock</span>
      <Shortcut os="mac" keys="Meta+Ctrl+Q" />
      <Shortcut os="windows" keys="Meta+L" />
      <Shortcut os="linux" keys="Meta+L" />
    </div>
  );
}

separator and variant

Omit separator and the platform convention is used: macOS runs the symbols together (⇧⌘P), the others join with +. Pass one and that character is used instead.

Key caps sit one step below the control heights, like a Chip, and are set in a monospaced face.

import { Shortcut } from 'neba';

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ShortcutVariants() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap items-center gap-4">
        <Shortcut keys="Mod+K" variant="solid" />
        <Shortcut keys="Mod+K" variant="outline" />
        <Shortcut keys="Mod+K" variant="text" />
        <Shortcut keys="Mod+K" variant="outline" color="primary" />
        <Shortcut keys="Mod+K" variant="solid" color="danger" />
      </div>

      <div className="flex flex-wrap items-center gap-4">
        {sizes.map((size) => (
          <Shortcut key={size} size={size} keys="Mod+K" />
        ))}
      </div>
    </div>
  );
}

Server rendering

os="auto" depends on the browser, so under SSR the first frame renders the default and switches to the real platform's spelling after hydration: a Mac reader sees Ctrl briefly, then ⌘. Name the os on screens where that transition matters.

Accessibility

• A screen reader cannot read a symbol like ⌘ as a key name. Every key drawn as a glyph carries a visually hidden name alongside it, so the shortcut is announced as "Command K".