Skip to Content
ComponentsFoundationFormSelect

Select

옵션을 선택하는 셀렉트 컴포넌트입니다.

개요

Select는 여러 옵션 중 하나 또는 여러 개를 선택할 수 있는 드롭다운 컴포넌트입니다. 검색 기능과 그룹 옵션을 지원합니다.

주요 특징:

  • Single / Multi select
  • Searchable select
  • 그룹 옵션
  • 커스텀 옵션 렌더링
  • 키보드 네비게이션

사용 사례:

  • 국가/지역 선택
  • 카테고리 선택
  • 필터 옵션
  • 설정 값 선택

설치

npx @vortex/cli add select --package foundation

기본 사용법

import { Select } from "@vortex/ui-foundation";
 
export default function Example() {
  return (
    <Select>
      <SelectTrigger>
        <SelectValue placeholder="선택하세요" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="1">Option 1</SelectItem>
        <SelectItem value="2">Option 2</SelectItem>
        <SelectItem value="3">Option 3</SelectItem>
      </SelectContent>
    </Select>
  );
}

Variants (변형)

Single Select (기본)

<Select onValueChange={(value) => console.log(value)}>
  <SelectTrigger>
    <SelectValue placeholder="하나만 선택" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">사과</SelectItem>
    <SelectItem value="banana">바나나</SelectItem>
    <SelectItem value="cherry">체리</SelectItem>
  </SelectContent>
</Select>

Multi Select

<Select multiple onValueChange={(values) => console.log(values)}>
  <SelectTrigger>
    <SelectValue placeholder="여러 개 선택" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">사과</SelectItem>
    <SelectItem value="banana">바나나</SelectItem>
    <SelectItem value="cherry">체리</SelectItem>
  </SelectContent>
</Select>

Searchable Select

<Select searchable>
  <SelectTrigger>
    <SelectValue placeholder="검색 가능" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="kr">한국</SelectItem>
    <SelectItem value="us">미국</SelectItem>
    <SelectItem value="jp">일본</SelectItem>
  </SelectContent>
</Select>

그룹 옵션

<Select>
  <SelectTrigger>
    <SelectValue placeholder="과일 선택" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>과일</SelectLabel>
      <SelectItem value="apple">사과</SelectItem>
      <SelectItem value="banana">바나나</SelectItem>
    </SelectGroup>
    <SelectGroup>
      <SelectLabel>채소</SelectLabel>
      <SelectItem value="carrot">당근</SelectItem>
      <SelectItem value="tomato">토마토</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Props API

PropTypeDefaultDescription
valuestring-선택된 값
defaultValuestring-기본 선택 값
multiplebooleanfalse다중 선택 허용
searchablebooleanfalse검색 기능
disabledbooleanfalse비활성화 상태
onValueChange(value) => void-값 변경 핸들러
classNamestring-추가 CSS 클래스

접근성

Select 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다.

ARIA 속성:

  • role="combobox" (자동 적용)
  • aria-expanded (드롭다운 열림/닫힘)
  • aria-activedescendant (현재 포커스된 옵션)

키보드 네비게이션:

  • Space / Enter: 드롭다운 열기
  • ↑ / ↓: 옵션 탐색
  • Enter: 옵션 선택
  • Esc: 드롭다운 닫기

예제

예제 1: 국가 선택

export default function CountrySelect() {
  const [country, setCountry] = useState("");
 
  return (
    <Select value={country} onValueChange={setCountry}>
      <SelectTrigger>
        <SelectValue placeholder="국가 선택" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="kr">대한민국</SelectItem>
        <SelectItem value="us">미국</SelectItem>
        <SelectItem value="jp">일본</SelectItem>
        <SelectItem value="cn">중국</SelectItem>
      </SelectContent>
    </Select>
  );
}

관련 컴포넌트

Last updated on
RadioSwitch