Select

미리 정의된 항목 중 하나 또는 여러 개를 선택하는 드롭다운 폼 컨트롤 컴포넌트

개요

Cals Select는 Foundation Combobox를 래핑하여 CALS 제품의 드롭다운 선택 UI를 선언적으로 구현하는 컴포넌트입니다.

주요 특징

• ✅ items 선언형 API: 배열 데이터만 넘기면 드롭다운 항목 자동 렌더링
• ✅ 단일/다중 선택: multiple prop으로 다중 선택 전환, 초과 선택은 +N으로 요약 표시
• ✅ 검색 필터: filterable prop으로 키보드 입력 실시간 필터링
• ✅ 빈 항목 추가: emptyOption prop으로 “전체” 등 빈 값 항목 추가
• ✅ 조건부 토큰 오버라이드: prop이 있을 때만 토큰 오버라이드 (기본값 보존)
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 가시성 제어: visible prop으로 선언적 표시/숨김
• ✅ 포커스 제어: ref.focus()/blur()/element로 프로그래밍 제어
• ✅ 디자인 토큰: Foundation 토큰 시스템 완벽 호환

기본 사용

items prop으로 드롭다운 항목 배열을 전달합니다. 각 항목은 value와 label을 가집니다.

<Select
  items={[
    { value: "apple", label: "사과" },
    { value: "banana", label: "바나나" },
    { value: "orange", label: "오렌지" },
  ]}
  placeholder="과일을 선택하세요"
/>

기본값 설정

defaultValue로 초기 선택값을 지정합니다.

<Select items={items} defaultValue="banana" />

크기

size prop으로 트리거 크기를 지정합니다. xs / sm / md / lg / xl을 지원합니다.

<Select items={items} size="xs" />
<Select items={items} size="sm" />
<Select items={items} size="md" />
<Select items={items} size="lg" />
<Select items={items} size="xl" />

입력 안내 텍스트

placeholder로 선택 전 안내 문구를 표시합니다. showPlaceholder=false이면 안내 문구를 숨깁니다.

<Select items={items} placeholder="원하는 과일을 선택하세요" />
<Select items={items} placeholder="숨김" showPlaceholder={false} />

비활성 / 읽기 전용

disabled로 비활성화하거나 readOnly로 읽기 전용으로 설정합니다. readOnly는 disabled와 동일하게 동작합니다 (원본 CALS 호환).

<Select items={items} disabled defaultValue="apple" />
<Select items={items} readOnly defaultValue="banana" />

목록 검색 필터

filterable=true이면 키보드 입력으로 항목을 실시간 필터링합니다. 기본(false)이면 입력 필드는 읽기 전용이지만 드롭다운은 정상 동작합니다.

<Select items={items} filterable placeholder="검색하여 선택" />

다중 선택

multiple=true이면 여러 항목을 선택할 수 있습니다. 선택된 항목은 chip으로 표시되며, maxDisplayChips를 초과한 선택은 +N으로 요약 표시됩니다.

<Select items={items} multiple defaultValue={["apple", "banana"]} />
<Select
  items={items}
  multiple
  maxDisplayChips={1}
  defaultValue={["apple", "banana", "orange"]}
/>

전체 선택 빈 항목

emptyOption으로 목록 첫 번째에 빈 값 항목을 추가합니다. true이면 기본 빈 항목, 객체이면 label/value를 지정합니다.

<Select items={items} emptyOption={{ label: "전체", value: "" }} />

FormItem 래핑

label, required, description, error prop을 지정하면 FormItem으로 자동 래핑됩니다.

<Select items={items} label="과일 선택" required placeholder="과일을 선택하세요" />
<Select items={items} label="에러 표시" error="필수 선택 항목입니다" />

레이블 위치

orientation=“horizontal”이면 레이블을 왼쪽에, “vertical”이면 위쪽에 배치합니다.

<Select items={items} label="과일" orientation="horizontal" />
<Select items={items} label="과일" orientation="vertical" />

커스텀 색상

backgroundColor, color, borderColor prop으로 토큰을 오버라이드합니다.

<Select items={items} backgroundColor="#7c3aed" color="#ffffff" defaultValue="apple" />
<Select items={items} borderColor="#e8553d" defaultValue="banana" />

API Reference

Props

SelectOption

Events

Ref (SelectRef)

접근성

권장 사항

• ✅ 각 항목에 의미 있는 label 텍스트를 제공합니다
• ✅ FormItem label을 사용하여 컨트롤 전체에 대한 설명을 제공합니다
• ✅ 키보드(Enter/Space/Arrow)로 드롭다운을 열고 항목을 탐색·선택할 수 있습니다
• ❌ 항목에 label 없이 value만 전달하지 마세요

관련 컴포넌트

• Foundation Combobox: 기본 Combobox 컴포넌트
• FormItem: 폼 래퍼
• RadioGroup: 소수의 항목 중 단일 선택이 필요한 경우