Skip to Content
ComponentsIcignalCombobox

Combobox

텍스트 입력과 옵션 선택이 결합된 검색형 선택 입력 요소

개요

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

주요 특징

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

Variants

단일 선택

다중 선택

그룹화 옵션

Variant 설명

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

Sizes

States

사용 예시

필수값 표시

required prop을 사용하면 레이블 좌측에 *(Asterisk)가 표시됩니다.

읽기 전용 상태

readOnly 상태에서는 선택된 값을 표시하지만 드롭다운이 열리지 않습니다.

pageviews
sessions

오류 상태 표시

error prop으로 오류 메시지를 표시하며, 오류 상태의 시각적 스타일을 적용합니다.

레이블 제공

orientation으로 레이블 배치 방향을, description으로 설명 텍스트를 제공합니다.

검색하여 항목을 선택해 주세요

옵션 아이콘 표시

옵션 항목에 아이콘을 함께 표시할 수 있습니다.

검색 결과 없음 표시

검색 결과가 없는 경우 emptyMessage로 안내 문구를 표시합니다.

값 초기화

showClear prop으로 선택된 값을 초기화하는 삭제(X) 버튼을 제공합니다.

pageviews
sessions

비활성화 옵션 표시

개별 항목에 disabled: true를 설정하면 선택 불가능한 상태로 표시됩니다.

분석 필터

지표와 태그를 검색하여 선택합니다.

프로젝트팀 구현 항목: 아래 기능은 프로젝트 요구사항에 맞춰 직접 구현합니다.

  • 미선택 상태 의미 규칙: 조회 조건 등에서 값이 선택되지 않은 상태(Placeholder 노출)는 전체 옵션을 선택한 것으로 해석

API Reference

Props

PropTypeDefaultDescription
itemsComboboxGroupData[][]그룹화된 항목 배열
multiplebooleanfalse다중 선택 모드
placeholderstring"Search..."플레이스홀더
emptyMessagestring"No results found."빈 결과 메시지
size"xs" | "sm" | "md" | "lg" | "xl""md"컴포넌트 크기
disabledbooleanfalse비활성화 여부
readOnlybooleanfalse읽기 전용 여부
showClearbooleanfalse클리어 버튼 표시
widthstring | number200컴포넌트 너비
valuestring | string[]-선택된 값 (제어)
defaultValuestring | string[]-기본 선택 값
labelstring-필드 레이블
labelWidthnumber-레이블 너비
labelAlign"start" | "center" | "end"-레이블 가로 정렬
labelVerticalAlign"start" | "center" | "end"-레이블 세로 정렬
requiredbooleanfalse필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

Events

EventTypeDescription
onValueChange(value: string | string[]) => void값 변경 시 호출

ComboboxGroupData

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

ComboboxItemData

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

기본 사용법

import { Combobox } from "@vortex/ui-icignal"
 
// 단일 선택
<Combobox
  label="메트릭"
  labelWidth={80}
  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
  label="메트릭 검색"
  placeholder="메트릭 검색..."
  items={[{ items: [{ value: "revenue", label: "매출" }] }]}
/>

권장 사항

  • ✅ label을 제공하여 선택 목적 전달
  • ✅ placeholder로 검색 가능함을 안내
  • ✅ 키보드: 입력으로 검색, Arrow로 이동, Enter로 선택
  • ✅ role="combobox", aria-expanded 자동 설정
  • ❌ 항목이 적은 경우 Select 사용 권장
  • ❌ placeholder만으로 레이블 대체 지양

관련 컴포넌트

Last updated on
ColorPickerDataTable