Combobox

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

검색이 필요할 만큼 긴 목록에서 고르세요. Combobox는 단일 선택과 여러 값용 Chips 레이아웃을 지원합니다(예: 역할). Input에 Field.Label이나 네이티브 label로 이름을 지으세요. Clear, Trigger, ChipRemove 액션 이름도 주세요. 명령과 그 설명처럼 라벨보다 많은 것을 보여 주는 옵션은 ItemContent 안에 ItemTitle과 ItemDescription을 두세요.

임의의 검색 텍스트를 유효한 선택으로 제출하지 마세요. 자유 텍스트가 유효하면 Autocomplete를 쓰세요. Autocomplete는 자유 텍스트를 저장합니다.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

Root → Field(label/description/error) + InputGroup(Input/Clear/Trigger or Chips) + Content(Portal/Positioner/Popup → Empty + List(Item(ItemContent(ItemTitle + ItemDescription)? / Indicator)))

키보드와 접근성

• 입력하면 목록이 필터링됩니다. Base UI는 한글 같은 IME 입력을 처리합니다.
• 화살표 키로 항목을 이동합니다.
• Enter는 항목을 선택합니다. 비활성 항목은 선택할 수 없습니다.
• Escape는 열린 팝업을 닫습니다. 팝업이 닫힌 상태에서 Escape는 선택을 지웁니다.
• 이름 있는 ChipRemove로 값을 하나 제거하세요.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Combobox, Field } from '@surflane/ui'

<Field.Root name='environment'>
  <Field.Label>Target environment</Field.Label>
  <Combobox.Root
    name='environment'
    items={environments}
    defaultValue='Staging web'
  >
    <Combobox.InputGroup>
      <Combobox.Input placeholder='Search environments…' />
      <Combobox.Clear />
      <Combobox.Trigger />
    </Combobox.InputGroup>
    <Combobox.Content>
      <Combobox.Empty>No matching environments.</Combobox.Empty>
      <Combobox.List>
        {(environment: string) => (
          <Combobox.Item key={environment} value={environment}>
            <Combobox.ItemIndicator />
            {environment}
          </Combobox.Item>
        )}
      </Combobox.List>
    </Combobox.Content>
  </Combobox.Root>
  <Field.Error />
</Field.Root>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰