useCombobox
useCombobox는 Combobox의 열림 상태, 값, 입력, 하이라이트, id를 관리합니다. 외형은 컴포넌트가 담당합니다. 입력은 Field, 표면은 Popover, BottomSheet, Dialog, 목록은 OptionList입니다. Combobox.* export는 없습니다. Combobox 레시피에서 단일, 다중, 시트, 비동기, 생성을 보여 줍니다.
presentation의 기본값은 'auto'이며, useSheetPresentation을 통해 coarse 포인터나 좁은 뷰포트에서 시트를 고릅니다. 고정하려면 popover나 sheet를 강제하세요. 아래 데모는 popover를 강제합니다. dialog는 Command palette처럼 입력과 목록을 Dialog에 둡니다. 어느 getter가 어느 파트에 가는지는 조합에 나와 있습니다.
React
Redux
Svelte
언제 쓰나요
언제: 검색 가능한 선택 — 타입어헤드 + 목록. 훅이 열림/값/입력을 관리하고, 레시피처럼 Field + Popover/BottomSheet + OptionList가 외형을 담당합니다. coarse/좁은 화면에서는 자동으로 시트.
쓰지 않을 때: 페이지에 고정된 배타적 선택 → Radio. 검색 없는 목록 → usePopover + OptionList만. 동작 메뉴 → Menu. Combobox.* 외형 export(금지).
Props
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| selectionMode | "single" | "multiple" | 아니요 | "single" | single은 TextInput을, multiple은 ChipInput을 씁니다. |
| options | readonly ComboboxOption[] | 아니요 | — | 동기 옵션. loadOptions가 설정되면 무시됩니다. |
| loadOptions | (query: string, signal: AbortSignal) => Promise<readonly ComboboxOption[]> | 아니요 | — | 비동기 옵션. 오래된 응답은 버립니다. 인라인 함수도 괜찮습니다. 호출 시점에 읽습니다. |
| loadKey | string | number | 아니요 | — | 바뀌면 옵션을 다시 불러옵니다. loadOptions가 카테고리처럼 쿼리 밖의 상태에 의존할 때 쓰세요. |
| presentation | "popover" | "sheet" | "dialog" | "auto" | 아니요 | "auto" | auto는 useSheetPresentation을 씁니다. dialog는 getDialogProps로 Dialog.Root에 씁니다. |
| allowCreate | boolean | 아니요 | false | 쿼리와 대소문자 구분 없이 일치하는 레이블이 없을 때 생성 행을 보여 줍니다. loadOptions가 있으면 그 쿼리의 로드가 끝날 때까지 행이 기다립니다. |
| value | string | null | readonly string[] | 아니요 | — | 제어 값. 비어 있는 single은 null, multiple은 배열. |
| open | boolean | 아니요 | — | 제어 열림. |
| inputValue | string | 아니요 | — | 제어 필터 텍스트. |