Select

드롭다운 형태의 선택 컴포넌트입니다.
검색, 그룹화, 키보드 네비게이션 등 다양한 기능을 지원합니다.

설치

Terminal

npx @msub-core/ui-cli add select

기본 사용

기본 드롭다운 선택 컴포넌트입니다.

TSX

import { Select } from "@msub-core/ui/components/select"

const fruits = [
  { value: "apple", label: "사과" },
  { value: "banana", label: "바나나" },
  { value: "orange", label: "오렌지" },
]

function Example() {
  const [value, setValue] = useState("")

  return (
    <Select
      options={fruits}
      value={value}
      onChange={setValue}
      placeholder="과일을 선택하세요"
    />
  )
}

Props

Prop	Type	Default	Required	Description
options	(SelectOption \| SelectOptionGroup)[]	-	Yes	옵션 목록
multiple	boolean	false	No	다중 선택 모드
value	string \| string[]	-	No	선택된 값 (controlled)
defaultValue	string \| string[]	-	No	기본 선택 값 (uncontrolled)
onChange	(value) => void	-	No	값 변경 핸들러
placeholder	string	"선택하세요"	No	placeholder 텍스트
label	string	-	No	라벨
helperText	string	-	No	도움말 텍스트
error	string	-	No	에러 메시지
size	"sm" \| "default" \| "lg"	"default"	No	크기
searchable	boolean	false	No	검색 가능 여부
clearable	boolean	false	No	클리어 버튼 표시 여부
disabled	boolean	-	No	비활성화 여부
maxSelect	number	-	No	최대 선택 개수 (multiple 모드)
displayMode	"tags" \| "count"	"tags"	No	선택 표시 방식 (multiple 모드)
emptyText	string	"결과가 없습니다"	No	검색 결과 없을 때 텍스트

라벨과 도움말

label, helperText, error props로 라벨과 도움말을 추가할 수 있습니다.

좋아하는 과일

하나를 선택해주세요

필수 선택

이 필드는 필수입니다

크기

size prop으로 크기를 조절할 수 있습니다.

검색 가능

searchable prop을 사용하면 옵션을 검색할 수 있습니다.

클리어 버튼

clearable prop을 사용하면 선택을 초기화할 수 있는 버튼이 표시됩니다.

옵션 그룹

옵션을 그룹으로 묶어서 표시할 수 있습니다.

국가 선택

TSX

const countries = [
  {
    label: "아시아",
    options: [
      { value: "kr", label: "대한민국" },
      { value: "jp", label: "일본" },
    ],
  },
  {
    label: "유럽",
    options: [
      { value: "uk", label: "영국" },
      { value: "fr", label: "프랑스" },
    ],
  },
]

<Select
  options={countries}
  placeholder="국가를 선택하세요"
/>

다중 선택

multiple prop을 사용하면 여러 옵션을 선택할 수 있습니다.

좋아하는 과일 (태그 모드)

좋아하는 과일 (카운트 모드)

TSX

<Select
  multiple
  options={fruits}
  value={selected}
  onChange={setSelected}
  placeholder="과일을 선택하세요"
  clearable
/>

다중 선택 + 그룹

다중 선택과 그룹화된 옵션을 함께 사용할 수 있습니다.

방문한 국가

최대 5개까지 선택 가능

비활성화

disabled prop으로 비활성화할 수 있습니다.

옵션 타입

SelectOption과 SelectOptionGroup 타입 정의입니다.

TSX

// 기본 옵션
interface SelectOption {
  value: string
  label: string
  disabled?: boolean
  icon?: React.ReactNode
}

// 옵션 그룹
interface SelectOptionGroup {
  label: string
  options: SelectOption[]
}

키보드 네비게이션

Enter / Space - 드롭다운 열기/선택
↑ ↓ - 옵션 탐색
Escape - 드롭다운 닫기
Tab - 다음 요소로 이동