Shortcut

키보드 단축키를 키캡 형태로 표시합니다. 플랫폼에 따라 수식 키의 표기가 자동으로 바뀝니다.

import { Shortcut } from 'neba';

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

Props

Prop	타입	기본값	설명
keys *	string | string[]	—	키들. 문자열은 +로 나뉩니다('Mod+Shift+P'). 키 자체가 +인 경우에만 배열형을 씁니다
os	'auto' | 'mac' | 'windows' | 'linux'	'auto'	어느 키보드로 읽을지. auto는 브라우저에 묻습니다. 나머지 셋은 읽는 사람의 플랫폼이 아니라 특정 플랫폼을 설명해야 하는 문서를 위한 것입니다
separator	ReactNode	—	키 사이에 오는 것. 생략하면 플랫폼의 관례를 따릅니다. Windows/Linux는 +, macOS는 아무것도 없이 ⇧⌘P
variant공통	'solid' | 'outline' | 'text'	'outline'	키캡의 무게. outline이 기본입니다. 지금까지 인쇄된 모든 설명서에서 키캡은 얇은 선의 상자였습니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	키캡의 높이와 타입 스케일. Chip처럼 컨트롤 사다리에서 한 단계 아래입니다. md 키캡은 sm 컨트롤입니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	의미론적 색 역할. 키캡은 액션이 아니라 화면의 부속이라 secondary가 기본입니다
density공통	'default' | 'compact'	'compact'	키캡의 좌우 여백만 바꿉니다. 기본이 compact인 이유는 키캡이 글줄 안에 들어앉기 때문입니다
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 이것은 키가 아니라 키의 그림이므로 올리고 싶은 마음이 드는 것이 함정입니다

MenuItem의 shortcut prop이 이 컴포넌트를 넣도록 마련된 자리입니다.

<MenuItem shortcut={<Shortcut keys="Mod+E" />}>이름 바꾸기</MenuItem>

예시

keys

문자열은 +를 기준으로 나뉩니다. 키 자체가 +일 때만 배열 형태가 필요합니다. 한 글자 토큰은 키캡 표기에 맞춰 대문자로 올라가고, 인식하지 못한 토큰은 넘긴 그대로 출력됩니다.

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와 Mod

Mod는 "그 플랫폼의 기본 수식 키"를 뜻하는 토큰입니다. macOS에서는 Command(⌘), 그 외에서는 Control로 해석됩니다. 표기만 바뀌는 다른 토큰과 달리 Mod는 가리키는 키 자체가 달라지는 유일한 토큰입니다.

os의 기본값 auto는 브라우저에 현재 플랫폼을 물어봅니다. mac · windows · linux를 명시하는 것은 특정 플랫폼을 설명하는 문서를 위한 것입니다.

같은 문자열을 라이브러리가 바인딩에도 씁니다. CommandPalette의 shortcut, TextField · NumberField · Combobox의 shortcuts가 모두 이 어휘를 읽습니다. 별칭도 마찬가지입니다. Cmd · Command · Meta · Win은 한 키이고, Esc · Return · Opt · Up은 각각 Escape · Enter · Alt · ArrowUp의 다른 표기입니다. 화면에 그린 키캡과 실제로 발동하는 키가 같은 문자열입니다.

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와 variant

separator를 생략하면 플랫폼 관례를 따릅니다. macOS는 기호를 붙여 쓰고(⇧⌘P), 나머지 플랫폼은 +로 잇습니다. 직접 넘기면 그 문자를 씁니다.

키캡은 Chip처럼 컨트롤 높이보다 한 단계 아래이고, 고정폭으로 조판됩니다.

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>
  );
}

서버 렌더링

os="auto"는 브라우저에 의존하므로 SSR에서는 첫 프레임이 기본값으로 렌더링된 뒤 hydration 이후 실제 플랫폼 표기로 바뀝니다. macOS에서는 Ctrl이 잠깐 보였다가 ⌘로 교체됩니다. 이 전환을 피해야 하는 화면에서는 os를 명시하세요.

접근성

• ⌘ 같은 기호는 screen reader가 키 이름으로 읽지 못합니다. 글리프로 그려지는 키는 시각적으로 숨긴 이름을 함께 담고 있어 "Command K"로 읽힙니다.