Combobox
텍스트 입력으로 컬렉션을 필터링하고 팝업에서 하나의 의미 있는 항목 값을 확정해요.
핵심 속성
| 속성 | 동작 |
|---|---|
| 상태 | 입력 텍스트, 선택 값, 열림 상태를 각각 제어형이나 비제어형으로 쓸 수 있어요. |
| 입력 구조 | Field.Root가 Field.Label과 Combobox.Root를 감싸고, Root 안에서 InputGroup이 선택적 InputAdornment + Input + Clear + Trigger를 담으며 Icon은 Trigger 안에 넣어요. |
| 다중 선택 구조 | Chips → Value → Chip + ChipRemove로 묶고 그리드 컬렉션은 Collection → Row → Item으로 구성해요. |
| 팝업 구조 | Portal → 선택적 Backdrop + Positioner → Popup → Arrow + Status + List 순서로 두고 Group, Indicator, Separator, Collection, Empty를 조합해요. |
| 상호작용 | 포인터, 방향키, Home/End, Enter, Escape, 필터링, 포커스 복원, 비활성 항목, 읽기 전용 루트 동작은 Base UI가 맡아요. |
| 폼 | Root에서 name, form, required, disabled, readOnly, 객체 직렬화, 네이티브 유효성 검사, 제출, 초기화를 지원해요. |
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/combobox.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRCombobox } from '@tinyrack/ui/components/combobox';
import { TRForm } from '@tinyrack/ui/components/form';
import { TRField } from '@tinyrack/ui/components/field';
import { TRButton } from '@tinyrack/ui/components/button';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
크기 고유 링크
InputGroup에 uiSize를 전달해 Combobox 높이를 인접한 Input, NumberField, Button과 맞춰 보세요.
필터 의미론 고유 링크
선택값과 입력 쿼리를 분리한 채 `contains`, `startsWith`, 내장 필터 없음 방식을 비교해요.
여러 칩과 그리드 컬렉션 고유 링크
Value는 제거 가능한 칩을 렌더링하고 Collection과 Row는 공개 그리드 구조를 노출해요.
제어 상태와 필터 훅 고유 링크
쿼리, 선택 값, 열림 상태를 독립적으로 제어하고 로케일 기반 필터 결과를 `useFilteredItems`로 읽어요.
오버레이 구성 고유 링크
Portal과 Positioner는 입력 레이아웃을 바꾸지 않고 팝업 위치를 맞춰요. Escape로 닫으면 포커스가 돌아와요.
키보드 선택 고유 링크
입력해 필터링하고 방향키로 이동한 뒤 Enter로 강조된 항목을 선택해요. Escape로 닫아요.
API
| 표면 | 용도 |
|---|---|
Root | 항목, 필터, 단일·다중 값, 입력 텍스트, 열림 상태, 유효성 검사, 폼 직렬화, 로케일, 객체 비교와 문자열 변환을 관리해요. |
InputGroup, InputAdornment, Input, Clear, Trigger, Icon | 편집 가능한 컨트롤을 구성해요. InputAdornment는 장식이고 Icon은 Trigger 안에 둬요. InputGroup은 uiSize?: 'md' | 'lg'를 받아 input, adornment, clear, trigger 높이를 함께 조절해요. |
Portal, Backdrop, Positioner, Popup, Arrow | 닫을 수 있는 오버레이를 마운트하고 배치해요. Portal은 사용자 지정 컨테이너를 지원하며 인라인이면 생략할 수 있어요. |
Status, List, Group, GroupLabel, Collection, Row, Item, ItemIndicator, Separator, Empty | 목록·그리드 컬렉션과 접근성 피드백을 렌더링해요. |
Chips, Value, Chip, ChipRemove | 여러 선택 값을 표시하고 제거해요. |
useFilter, useFilteredItems | 로케일 기반 contains, startsWith, endsWith 조건자를 만들고 Root 안에서 제네릭 필터링 항목 배열을 읽어요. |
모든 파트는 개별 TRCombobox* 내보내기와 속성·상태 타입을 제공해요. Root 동작, 상태 변경 및 강조 표시의 세부 정보·이유 타입과 TRComboboxFilter, TRComboboxFilterOptions도 내보내요.
편집 가능한 Input은 TRField.Root로 감싸고 TRField.Label로 이름을 붙이세요. 레이블은 등록된 컨트롤에서 htmlFor를 스스로 찾으니 id나 useId를 직접 지정하지 않아도 돼요. TRCombobox.Label은 트리거만 있는 선택 구조 전용이에요. InputGroup은 uiSize?: 'md' | 'lg'(기본값 md)를 받아 input, adornment, clear, trigger 높이를 인접한 컨트롤과 맞춰요. 비활성화된 루트나 항목은 변경할 수 없고 읽기 전용 루트는 포커스할 수 있지만 입력하거나 지울 수 없어요. 객체 값은 안정적인 동일성을 유지하고 { label, value } 규칙으로 충분하지 않으면 itemToStringLabel, itemToStringValue, isItemEqualToValue를 지정해요.
Combobox 모듈은 SSR에 안전해요. Portal은 하이드레이션 후 마운트되며 서버와 클라이언트의 초기 제어 값이 같아야 해요. 스타일은 combobox.css로 별도 제공해요. --tr-combobox-input-background, --tr-combobox-content-background, --tr-combobox-content-max-height, --tr-combobox-content-max-width, --tr-combobox-option-min-height로 모양을 조정할 수 있고 밝은·어두운 테마의 의미형 토큰으로 대체돼요.