Autocomplete
자유 형식 텍스트를 입력받고 알려진 컬렉션의 제안을 필터링해 알려줘요.
핵심 속성
| 속성 | 동작 |
|---|---|
| 값 | 항목과 일치하지 않아도 텍스트 값을 자유롭게 편집할 수 있어요. |
| 입력 구조 | Label → InputGroup → 선택적 InputAdornment + Input + Clear + Trigger 순서이며, Icon은 Trigger 안에 둬요. |
| 팝업 구조 | Status가 결과를 알리고 List가 그룹, 항목, 구분선, Empty 피드백을 포함해요. |
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/autocomplete.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRAutocomplete } from '@tinyrack/ui/components/autocomplete';
import { TRForm } from '@tinyrack/ui/components/form';
import { TRField } from '@tinyrack/ui/components/field';
import { TRButton } from '@tinyrack/ui/components/button';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
크기 고유 링크
InputGroup에 uiSize를 전달해 Autocomplete 높이를 인접한 Input, NumberField, Button과 맞춰 보세요.
입력 완성 모드 고유 링크
제안 목록, 목록과 인라인 완성, 인라인 완성만 사용, 완성 기능 끄기 중에서 선택해요.
옵션과 결과 상태 고유 링크
사용 가능한 컬렉션, 비활성 옵션, 빈 결과를 루트의 사용 가능 상태와 섞지 않고 비교해요.
자유 입력 의미론 고유 링크
컬렉션 밖의 값을 그대로 입력할 수 있고, 제안을 선택하면 같은 편집 가능한 텍스트 값이 갱신돼요.
오버레이 구성 고유 링크
Portal은 팝업을 컨트롤 밖에 마운트하고 Positioner는 위치를 맞춰요. Escape를 누르면 닫히고 포커스가 돌아와요.
키보드 선택 고유 링크
입력해 필터링하고 방향키로 강조 항목을 옮긴 뒤 Enter로 선택해요. Escape를 누르면 팝업이 닫혀요.
네이티브 폼 재설정 고유 링크
재설정하면 비제어 기본값이 복원되고 제출 결과가 지워져요.
API
@tinyrack/ui/components/autocomplete는 Root, Value, Trigger, Input, InputGroup, Icon, Clear, List, Status, Portal, Backdrop, Positioner, Popup, Arrow, Group, GroupLabel, Item, Row, Collection, Empty, Separator의 전체 Base UI 구조를 내보내요. InputAdornment는 Tinyrack이 제공하는 입력 장식 파트예요. InputGroup은 uiSize?: 'md' | 'lg'(기본값 md)를 받아 input, adornment, clear, trigger 높이를 인접한 컨트롤과 맞춰요. 각 파트의 이름 있는 export와 prop type 외에도 Base UI state, root action/event-detail, filter, filter-option type을 TRAutocomplete* 이름으로 제공해요. 로케일 인식 매칭에는 useAutocompleteFilter/TRAutocomplete.useFilter를 사용하고, Root 안에서 필터링된 컬렉션을 읽으려면 useAutocompleteFilteredItems/TRAutocomplete.useFilteredItems를 사용하세요.