Skip to Content
ComponentsFoundationCommand

Command

검색과 키보드 탐색이 가능한 커맨드 팔레트 컴포넌트

개요

Command 컴포넌트는 cmdk 기반으로 검색 입력, 항목 필터링, 키보드 탐색을 제공하는 커맨드 메뉴입니다. 인라인으로 사용하거나 CommandDialog로 모달 팔레트 형태(⌘K 스타일)로 사용할 수 있습니다.

주요 특징

  • ✅ 검색 필터링: 입력 텍스트에 따라 항목 자동 필터링
  • ✅ 그룹화: CommandGroup으로 항목을 섹션별로 구분
  • ✅ 단축키 표시: CommandShortcut으로 키 바인딩 힌트 표시
  • ✅ 다이얼로그 모드: CommandDialog로 모달 커맨드 팔레트 구성
  • ✅ 키보드 탐색: 방향키/Enter로 항목 탐색 및 실행
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 사용

검색 입력, 그룹, 구분선, 단축키를 포함한 인라인 커맨드 메뉴입니다.

커맨드 다이얼로그

CommandDialog로 모달 형태의 커맨드 팔레트를 구성합니다. ⌘K 등의 전역 단축키와 함께 사용하는 것이 일반적입니다. 아래 Preview는 다이얼로그 내부에 렌더링되는 콘텐츠를 보여줍니다.

API Reference

Command Props

cmdk의 Command props를 모두 상속합니다.

PropTypeDefaultDescription
valuestring-선택된 항목 값 (제어 모드)
onValueChange(value: string) => void-선택 값 변경 콜백
filterfunction-커스텀 필터 함수
loopbooleanfalse항목 탐색 순환 여부
classNamestring-추가 CSS 클래스

CommandDialog Props

Dialog props를 상속하며, 내부에 Command를 배치합니다.

PropTypeDefaultDescription
openboolean-열림 상태 (제어 모드)
onOpenChange(open: boolean) => void-열림 상태 변경 콜백
titlestring"Command Palette"접근성용 제목 (시각적으로 숨김)
descriptionstring"Search for a command to run..."접근성용 설명 (시각적으로 숨김)
showCloseButtonbooleanfalse닫기 버튼 표시
classNamestring-추가 CSS 클래스

CommandInput Props

PropTypeDefaultDescription
placeholderstring-입력 플레이스홀더
valuestring-검색어 (제어 모드)
onValueChange(value: string) => void-검색어 변경 콜백

CommandGroup Props

PropTypeDefaultDescription
headingstring-그룹 제목

CommandItem Props

PropTypeDefaultDescription
valuestring-항목 값 (검색 대상)
keywordsstring[]-추가 검색 키워드
disabledbooleanfalse항목 비활성화
onSelect(value: string) => void-항목 선택 시 콜백

기본 사용법

import {
  Command,
  CommandDialog,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandItem,
  CommandShortcut,
  CommandSeparator,
} from "@vortex/ui-foundation"
 
<Command>
  <CommandInput placeholder="검색..." />
  <CommandList>
    <CommandEmpty>결과가 없습니다.</CommandEmpty>
    <CommandGroup heading="제안">
      <CommandItem onSelect={() => console.log("선택됨")}>
        캘린더
        <CommandShortcut>⌘P</CommandShortcut>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

접근성

시맨틱 마크업

  • cmdk 기반으로 입력창에 role="combobox", 목록에 role="listbox", 항목에 role="option" 자동 적용
  • aria-expanded, aria-activedescendant 등 상태 속성 자동 관리
  • CommandDialog는 Dialog 기반으로 포커스 트랩과 aria-modal 적용

키보드 지원

  • ✅ ↑ / ↓로 항목 탐색
  • ✅ Enter로 항목 선택
  • ✅ Esc로 다이얼로그 닫기 (CommandDialog)

관련 컴포넌트

  • Dialog: CommandDialog의 기반이 되는 모달
  • Combobox: 검색 가능한 선택 입력 컴포넌트
  • DropdownMenu: 트리거 기반 메뉴 표시
Last updated on
ComboboxContext Menu