Skip to Content
ComponentsIcignalCombobox

Combobox

검색 가능한 드롭다운 선택 컴포넌트

개요

Combobox는 검색 필터링이 가능한 드롭다운 선택 컴포넌트입니다. 대량의 항목에서 빠르게 원하는 옵션을 찾을 수 있으며, 단일/다중 선택을 모두 지원합니다.

주요 특징

  • ✅ 검색 필터링: 입력으로 항목 실시간 검색
  • ✅ 단일/다중 선택: 칩 기반 다중 선택
  • ✅ 그룹화 옵션: 카테고리별 항목 분류
  • ✅ 아이콘/단축키: 항목에 아이콘, 단축키 표시
  • ✅ 다양한 크기: xs, sm, md, lg, xl
  • ✅ 접근성: WAI-ARIA Combobox 패턴
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

Variants

단일 선택

다중 선택

그룹화 옵션

Variant 설명

Variant설명사용 사례
single검색 후 하나 선택메트릭 선택
multiple검색 후 여러 개 선택 (칩)채널/태그 필터
grouped카테고리별 그룹 표시카테고리별 메트릭

Sizes

States

사용 예시

예시 1: 지표 검색

대량의 분석 지표 중 검색하여 선택합니다.

예시 2: 다중 필터 선택

리포트에 포함할 여러 항목을 선택합니다.

API Reference

Props

PropTypeDefaultDescription
itemsComboboxGroupData[][]그룹화된 항목 배열
multiplebooleanfalse다중 선택 모드
placeholderstring"Search..."플레이스홀더
emptyMessagestring"No results found."빈 결과 메시지
size"xs" | "sm" | "md" | "lg" | "xl""md"컴포넌트 크기
disabledbooleanfalse비활성화 여부
showClearbooleanfalse클리어 버튼 표시
widthstring | number200컴포넌트 너비
valuestring | string[]-선택된 값 (제어)
defaultValuestring | string[]-기본 선택 값
onValueChange(value) => void-값 변경 핸들러
classNamestring-추가 CSS 클래스

ComboboxGroupData

PropTypeDefaultDescription
labelstring-그룹 레이블
itemsComboboxItemData[]-그룹 내 항목들

ComboboxItemData

PropTypeDefaultDescription
valuestring-옵션 값 (필수)
labelstring-옵션 레이블
iconReactNode-아이콘
shortcutstring-단축키 표시
disabledbooleanfalse비활성화 여부

기본 사용법

import { Combobox } from "@vortex/ui-icignal"
 
// 단일 선택
<Combobox
  placeholder="검색..."
  items={[
    {
      items: [
        { value: "a", label: "옵션 A" },
        { value: "b", label: "옵션 B" },
      ],
    },
  ]}
/>
 
// 그룹화
<Combobox
  placeholder="검색..."
  items={[
    { label: "그룹 1", items: [{ value: "a", label: "A" }] },
    { label: "그룹 2", items: [{ value: "b", label: "B" }] },
  ]}
/>
 
// 다중 선택
<Combobox multiple placeholder="검색..." items={[...]} />

접근성

ARIA 속성

<Combobox
  placeholder="메트릭 검색..."
  items={[{ items: [{ value: "revenue", label: "매출" }] }]}
/>

권장 사항

  • ✅ placeholder로 검색 가능함을 안내
  • ✅ 키보드: 입력으로 검색, Arrow로 이동, Enter로 선택
  • ✅ role="combobox", aria-expanded 자동 설정
  • ❌ 항목이 적은 경우 Select 사용 권장

관련 컴포넌트

Last updated on
CheckboxGroupDataTable