CommandPalette

이름을 입력해 찾고, 골라서 실행해요. 항목이 많을 때 써요. 폼 안에서 값 하나를 골라 둘 때는 Combobox를 써요.

사용 예시

문서와 사람 찾아가기

tsx

<Button color="neutral" emphasis="outline" onClick={() => setOpen(true)}>  <Search />  빠른 이동</Button><CommandPalette  open={open}  onOpenChange={setOpen}  items={destinations}  title="빠른 이동"  placeholder="문서나 사람 이름을 입력하세요"  emptyText="검색 결과가 없어요"  onSelect={value => router.push(value)}/>

const destinations = [  { value: '/docs/brand-guide/', label: '브랜드 가이드', description: '문서' },  { value: '/docs/remote-work/', label: '원격 근무 규정', description: '문서' },  { value: '/docs/quarterly-report/', label: '분기 보고서', description: '문서' },]

권장

검색할 말이 label에 다 있어요. 브랜드를 입력하면 브랜드 가이드가 보여요.

const destinations = [  { value: '/docs/brand-guide/', label: '가이드', description: '브랜드' },  { value: '/docs/remote-work/', label: '규정', description: '원격 근무' },  { value: '/docs/quarterly-report/', label: '보고서', description: '분기' },]

지양

description에 적은 말로는 찾을 수 없어요. 보이는 이름을 짧게 두려면 textValue에 찾을 말을 적으세요.

단축키로 열기

단축키는 호출하는 쪽에서 등록해요. Ctrl과 K를 함께 눌러 보세요.

const [open, setOpen] = useState(false)useEffect(() => {  const onKey = (e: KeyboardEvent) => {    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {      e.preventDefault()      setOpen(true)    }  }  window.addEventListener('keydown', onKey)  return () => window.removeEventListener('keydown', onKey)}, [])

권장

단축키가 버튼에 적혀 있어서 한 번 본 사람은 다음부터 키로 열 수 있어요.

지양

단축키를 알 방법이 없어서 매번 버튼을 눌러 열어야 해요.

화면 안의 명령

화면 안에서 실행할 명령을 고를 때도 써요.

휴가는 쓰기 2일 전까지 신청해요. 반나절 단위로도 쓸 수 있고, 남은 휴가는 다음 해 3월까지 이월돼요.

tsx

<Button color="neutral" emphasis="outline" onClick={() => setOpen(true)}>  <Command />  명령 고르기</Button><CommandPalette  open={open}  onOpenChange={setOpen}  items={commands}  title="명령 고르기"  placeholder="명령 이름을 입력하세요"  emptyText="검색 결과가 없어요"  onSelect={run}/>

권장

버튼 3개가 한눈에 보이고, 한 번만 누르면 돼요.

지양

3개 중 하나를 고르려고 CommandPalette를 열면 단계가 하나 늘어나요.

결과 없음

초성으로는 찾을 수 없어요.

tsx

<Button color="neutral" emphasis="outline" onClick={() => setOpen(true)}>빠른 이동</Button><CommandPalette  open={open}  onOpenChange={setOpen}  items={destinations}  emptyText="그런 이름이 없어요"  title="빠른 이동"  placeholder="문서나 사람 이름을 입력하세요"/>

긴 목록

항목이 많아도 높이는 늘어나지 않고 목록 안쪽이 스크롤돼요. 이 높이는 바꿀 수 없어요.

최근에 연 것

items를 넘긴 순서대로 보여요. 최근 항목을 위에 보여 주려면 배열 앞에 두세요.

const recent = ['/people/seoyeon/', '/docs/brand-guide/']const items = [  ...destinations    .filter(item => recent.includes(item.value))    .map(item => ({ ...item, description: '최근' })),  ...destinations.filter(item => !recent.includes(item.value)),]

그룹

항목이 종류별로 나뉠 때 써요. 검색 결과가 없는 그룹은 이름도 숨어요.

tsx

const groups = [  {    label: '문서',    items: [      { value: '/docs/brand-guide/', label: '브랜드 가이드' },      { value: '/docs/remote-work/', label: '원격 근무 규정' },    ],  },  {    label: '사람',    items: [      { value: '/people/seoyeon/', label: '김서연' },      { value: '/people/doyun/', label: '박도윤' },    ],  },]<CommandPalette  open={open}  onOpenChange={setOpen}  items={groups}  title="빠른 이동"  placeholder="문서나 사람 이름을 입력하세요"  emptyText="검색 결과가 없어요"/>

명세

이름
이름	값	기본
CommandPalette
items	CommandPaletteItem[], CommandPaletteGroup[]	필수
필터하기 전의 항목 전부를 넘겨요.
title	string	필수
화면에 보이지 않고 스크린 리더가 읽는 이름이에요.
description	string	-
화면에 보이지 않고 스크린 리더가 이름 다음에 읽어요. placeholder와 다른 안내가 있을 때만 넘겨요.
placeholder	string	필수
emptyText	string	필수
입력한 글자에 맞는 항목이 없을 때 목록 대신 보여요.
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요. 닫히면 입력한 검색어가 지워져요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean) => void	-
열리거나 닫히면 호출돼요.
className	string	-
DialogContent에 적용돼요.
onSelect	(value: string) => void	-
항목을 고르면 호출되고 CommandPalette가 닫혀요.
CommandPaletteItem
value	string	필수
고르면 onSelect로 전달되는 값이에요.
label	string	필수
목록에 보이는 이름이에요.
description	string	-
label 아래에 한 줄로 보여요.
textValue	string	label
검색할 때 이 글자와 맞춰 봐요.
CommandPaletteGroup
label	string	필수
목록에서 그룹 위에 보이는 이름이에요.
items	CommandPaletteItem[]	필수
이 그룹의 항목이에요.