Skip to content
Docs
컴포넌트로 돌아가기

Command

@hua-labs/ui
v1.0.0

빠른 탐색과 액션을 위한 커맨드 팔레트 컴포넌트입니다. 키보드 단축키, 검색 필터링, 그룹화된 아이템을 지원합니다.

설치

bash
npm install @hua-labs/hua
Import
tsx
import { Command, CommandItem, CommandGroup, CommandSeparator, CommandEmpty } from "@hua-labs/hua";

@hua-labs/ui의 UI 컴포넌트를 @hua-labs/hua에서 통합 제공합니다.

UI 컴포넌트, 모션 훅, i18n을 하나의 패키지로 사용할 수 있습니다.

라이브 데모

기본 사용법

또는 Cmd+K / Ctrl+K

그룹 사용

검색 필터링

Props

이름타입기본값설명
openboolean-제어 모드 열림 상태
onOpenChange(open: boolean) => void-열림 상태 변경 콜백
placeholderstring"명령어를 검색하세요..."검색 입력 플레이스홀더
searchValuestring-제어 모드 검색 값
onSearchChange(value: string) => void-검색 값 변경 콜백
disabledbooleanfalse커맨드 팔레트 비활성화

CommandItem Props

PropTypeDefault설명
iconReact.ReactNode-docs:components.command.itemProps.icon
selectedbooleanfalsedocs:components.command.itemProps.selected
onSelect() => void-docs:components.command.itemProps.onSelect

코드 예시

docs:common.basicUsagetsx
1// Via framework (recommended)
2import {
3  Command,
4  CommandItem,
5  CommandGroup,
6  CommandSeparator,
7} from '@hua-labs/ui/interactive';
8// Or direct import
9// import { Command, CommandItem, CommandGroup, CommandSeparator } from '@hua-labs/ui/interactive';
10 
11const [open, setOpen] = useState(false);
12 
13<Button onClick={() => setOpen(true)}>
14  Open Command Palette
15</Button>
16 
17<Command open={open} onOpenChange={setOpen}>
18  <CommandItem icon={<File />} onSelect={() => console.log('New File')}>
19    New File
20  </CommandItem>
21  <CommandItem icon={<FolderOpen />} onSelect={() => console.log('Open')}>
22    Open...
23  </CommandItem>
24  <CommandSeparator />
25  <CommandItem icon={<Gear />} onSelect={() => console.log('Settings')}>
26    Settings
27  </CommandItem>
28</Command>
docs:components.command.examples.withGroupstsx
1<Command open={open} onOpenChange={setOpen}>
2  <CommandGroup heading="File">
3    <CommandItem icon={<Plus />}>New File</CommandItem>
4    <CommandItem icon={<FolderOpen />}>Open...</CommandItem>
5  </CommandGroup>
6  <CommandSeparator />
7  <CommandGroup heading="Edit">
8    <CommandItem icon={<Copy />}>Copy</CommandItem>
9    <CommandItem icon={<Trash />} disabled>Delete</CommandItem>
10  </CommandGroup>
11</Command>
docs:components.command.examples.withSearchFilteringtsx
1const [searchValue, setSearchValue] = useState('');
2 
3const items = [
4  { label: 'Home', icon: <House /> },
5  { label: 'Settings', icon: <Gear /> },
6  { label: 'Profile', icon: <User /> },
7];
8 
9const filtered = items.filter(item =>
10  item.label.toLowerCase().includes(searchValue.toLowerCase())
11);
12 
13<Command
14  open={open}
15  onOpenChange={setOpen}
16  searchValue={searchValue}
17  onSearchChange={setSearchValue}
18  placeholder="Search commands..."
19>
20  {filtered.length === 0 ? (
21    <CommandEmpty>No results found</CommandEmpty>
22  ) : (
23    filtered.map(item => (
24      <CommandItem key={item.label} icon={item.icon}>
25        {item.label}
26      </CommandItem>
27    ))
28  )}
29</Command>

하위 컴포넌트

  • • CommandItem - 메뉴 아이템
  • • CommandGroup - 아이템 그룹 (heading prop으로 제목 설정)
  • • CommandSeparator - 구분선
  • • CommandEmpty - 결과 없음 표시
  • • CommandDialog - Command의 별칭

접근성

  • •키보드 단축키: Cmd+K (Mac) 또는 Ctrl+K (Windows)로 토글
  • •화살표 탐색: ↑↓ 키로 아이템 탐색
  • •선택: Enter 키로 포커스된 아이템 선택
  • •닫기: Escape 키 또는 외부 클릭으로 닫기