Select

트리거를 누르면 열리는 목록에서 값 하나를 골라요. 배송 방법이나 결제 수단처럼 정해진 선택지 중에서 고를 때 써요. 선택지가 많아 검색해야 하면 Combobox를, 동작을 실행할 때는 DropdownMenu를 써요.

사용 예시

값 하나 고르기

고른 항목의 글자가 트리거에 보여요. SelectItem을 다른 컴포넌트로 감싸면 트리거가 글자를 찾지 못해서 items로 넘겨요.

tsx

<Select placeholder="결제 수단을 고르세요" aria-label="결제 수단">  <SelectItem value="card">    <SelectItemText>신용카드</SelectItemText>  </SelectItem>  <SelectItem value="transfer">    <SelectItemText>계좌 이체</SelectItemText>  </SelectItem>  <SelectItem value="phone">    <SelectItemText>휴대폰 결제</SelectItemText>  </SelectItem>  <SelectItem value="easy">    <SelectItemText>간편 결제</SelectItemText>  </SelectItem></Select>

매달

분기마다

해마다

권장

선택지가 적으면 RadioGroup을 써요. 목록을 열지 않아도 모든 선택지가 보여서 빨리 고를 수 있어요.

지양

Select는 트리거를 눌러야 선택지가 보여요. 선택지가 많거나 공간이 좁을 때 Select를 써요.

권장

고른 값이 트리거에 남아서 목록을 닫아도 지금 정렬 기준을 알 수 있어요.

지양

내보내기를 골라도 아무 일도 일어나지 않고, 트리거에 남은 내보내기가 지금 상태처럼 보여요. 동작 목록에는 DropdownMenu를 써요.

항목 설명

이름만으로 항목을 구분하기 어려울 때 써요. 설명은 목록에만 나오고 트리거에는 이름만 보여요.

tsx

<Select placeholder="배송 방법을 고르세요" aria-label="배송 방법">  <SelectItem value="standard">    <SelectItemText>일반 배송</SelectItemText>    <SelectItemDescription>주문 다음 날부터 2일 걸려요</SelectItemDescription>  </SelectItem>  <SelectItem value="dawn">    <SelectItemText>새벽 배송</SelectItemText>    <SelectItemDescription>자정 전에 주문하면 아침에 와요</SelectItemDescription>  </SelectItem>  <SelectItem value="pickup">    <SelectItemText>방문 수령</SelectItemText>    <SelectItemDescription>매장에서 직접 받아요</SelectItemDescription>  </SelectItem></Select>

권장

placeholder로 트리거에 고를 대상을 적어요. 값을 고르면 placeholder는 사라져요.

지양

placeholder가 없으면 트리거가 비어 보여요. 트리거를 눌러 보기 전에는 고를 항목을 알 수 없어요.

그룹과 구분선

항목이 종류별로 나뉠 때 써요. 그룹 이름이 필요 없으면 SelectSeparator만 둬요.

tsx

<Select placeholder="통화를 고르세요" aria-label="통화">  <SelectGroup label="아시아">    <SelectItem value="krw">      <SelectItemText>원</SelectItemText>    </SelectItem>    <SelectItem value="jpy">      <SelectItemText>엔</SelectItemText>    </SelectItem>  </SelectGroup>  <SelectSeparator />  <SelectGroup label="유럽과 미주">    <SelectItem value="usd">      <SelectItemText>달러</SelectItemText>    </SelectItem>    <SelectItem value="eur">      <SelectItemText>유로</SelectItemText>    </SelectItem>    <SelectItem value="gbp">      <SelectItemText>파운드</SelectItemText>    </SelectItem>  </SelectGroup></Select>

라벨과 도움말

Field로 감싸면 라벨과 도움말이 트리거에 연결돼요. 값이 올바르지 않으면 Field에 invalid를 주고 FieldError에 필요한 값을 적어요.

배송 방법

새벽 배송은 일부 지역에서만 돼요.

결제 수단

결제하기 전에 수단을 골라야 해요.

tsx

<Field>  <FieldLabel>배송 방법</FieldLabel>  <Select placeholder="배송 방법을 고르세요">    <SelectItem value="standard">      <SelectItemText>일반 배송</SelectItemText>    </SelectItem>    <SelectItem value="dawn">      <SelectItemText>새벽 배송</SelectItemText>    </SelectItem>  </Select>  <FieldHelp>새벽 배송은 일부 지역에서만 돼요.</FieldHelp></Field><Field invalid>  <FieldLabel>결제 수단</FieldLabel>  <Select placeholder="결제 수단을 고르세요">    <SelectItem value="card">      <SelectItemText>신용카드</SelectItemText>    </SelectItem>    <SelectItem value="transfer">      <SelectItemText>계좌 이체</SelectItemText>    </SelectItem>  </Select>  <FieldError>결제하기 전에 수단을 골라야 해요.</FieldError></Field>

배송 방법

권장

라벨은 값을 고른 뒤에도 보여요. 나중에 다시 봐도 이 값의 뜻을 알 수 있어요.

지양

placeholder로 라벨을 대신하면 값을 고르는 순간 사라져요.

배경

Select 여러 개가 나란히 있으면 bare를 써요. 하나만 있거나 고르는 곳이 먼저 눈에 띄어야 하면 well을 써요.

tsx

<Select placeholder="배송 방법을 고르세요" aria-label="배송 방법">  <SelectItem value="standard">    <SelectItemText>일반 배송</SelectItemText>  </SelectItem></Select><Select surface="well" placeholder="배송 방법을 고르세요" aria-label="배송 방법">  <SelectItem value="standard">    <SelectItemText>일반 배송</SelectItemText>  </SelectItem></Select>

문장 안에서 고르기

설정을 문장처럼 읽게 할 때 써요. 펼침 아이콘은 평소에 옅게 보여요.

반복, 알림

tsx

<p className="text-value flex flex-wrap items-center gap-1">  <span>반복</span>  <Select surface="ghost" value={repeat} onValueChange={setRepeat} aria-label="반복" className="w-auto">    <SelectItem value="day">      <SelectItemText>날마다</SelectItemText>    </SelectItem>    <SelectItem value="week">      <SelectItemText>주마다</SelectItemText>    </SelectItem>    <SelectItem value="month">      <SelectItemText>달마다</SelectItemText>    </SelectItem>  </Select>  <span>, 알림</span>  <Select surface="ghost" value={alarm} onValueChange={setAlarm} aria-label="알림" className="w-auto">    <SelectItem value="10">      <SelectItemText>10분 전</SelectItemText>    </SelectItem>    <SelectItem value="60">      <SelectItemText>1시간 전</SelectItemText>    </SelectItem>  </Select></p>

폼에서는 bare

배송 방법

권장

폼에서는 테두리가 있는 bare를 써요. 고를 수 있는 곳이 바로 보여요.

배송 방법

지양

폼에서 ghost를 쓰면 Select가 글자처럼 보여서 이미 정해진 값으로 읽혀요.

Input 옆

옆에 있는 컨트롤과 size를 맞춰요. Input과 버튼이 lg면 Select도 lg예요.

tsx

<div className="flex gap-2">  <Input className="min-w-0" placeholder="보낼 금액을 입력하세요" />  <div className="w-40 shrink-0">    <Select placeholder="통화" aria-label="통화">      <SelectItem value="krw">        <SelectItemText>원</SelectItemText>      </SelectItem>      <SelectItem value="usd">        <SelectItemText>달러</SelectItemText>      </SelectItem>    </Select>  </div>  <Button color="brand" emphasis="solid">보내기</Button></div>

비활성

값을 바꿀 수 없을 때는 Select에, 고를 수 없는 항목이 있을 때는 그 SelectItem에 disabled를 줘요.

tsx

<Select value={method} onValueChange={setMethod} disabled aria-label="결제 수단">  <SelectItem value="card">    <SelectItemText>신용카드</SelectItemText>  </SelectItem></Select><Select placeholder="배송 방법을 고르세요" aria-label="배송 방법">  <SelectItem value="standard">    <SelectItemText>일반 배송</SelectItemText>  </SelectItem>  <SelectItem value="dawn">    <SelectItemText>새벽 배송</SelectItemText>  </SelectItem>  <SelectItem value="pickup" disabled>    <SelectItemText>방문 수령</SelectItemText>    <SelectItemDescription>가까운 매장이 없어요</SelectItemDescription>  </SelectItem></Select>

컨트롤

surface

size

arrow

disabled

값null

tsx

<Select value={shipping} onValueChange={setShipping} placeholder="배송 방법을 고르세요" aria-label="배송 방법">  <SelectItem value="standard">    <SelectItemText>일반 배송</SelectItemText>  </SelectItem>  <SelectItem value="dawn">    <SelectItemText>새벽 배송</SelectItemText>  </SelectItem>  <SelectItem value="pickup">    <SelectItemText>방문 수령</SelectItemText>  </SelectItem></Select>

명세

이름
이름	값	기본
Select
value	string \| null	-
호출하는 쪽에서 고른 항목을 관리해요. 고르지 않았으면 null이에요.
defaultValue	string \| null	-
처음 값이에요.
onValueChange	(value: string \| null, eventDetails) => void	-
고른 항목이 바뀌면 호출돼요.
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean, eventDetails) => void	-
열리거나 닫히면 호출돼요.
placeholder	string	-
surface	bare, well, ghost	bare
bare는 투명 배경에 테두리, well은 회색 배경이에요. ghost는 평소에 글자만 보이고, 마우스를 올리면 옅은 배경, 열면 조금 진한 배경이 생겨요. 여러 개가 나란히 있으면 bare, 하나만 있으면 well, 문장이나 표 셀 안에서 값을 바로 바꾸면 ghost를 써요.
size	sm, md, lg	md
높이가 32, 36, 40px이에요.
arrow	boolean	false
목록에 트리거를 가리키는 화살표를 보여요.
sideOffset	number, 함수	8, arrow가 있으면 14
기준과 떨어진 거리예요. 단위는 px이에요.
alignOffset	number, 함수	0
align 방향으로 옮기는 거리예요. 단위는 px이에요.
collisionAvoidance	object	-
화면 가장자리에 닿을 때 뒤집을지, 밀어 넣을지 정해요. Base UI Positioner의 값을 그대로 받아요.
disabled	boolean	false
className	string	-
모든 하위 컴포넌트에 쓸 수 있어요. Select에서는 트리거에 적용돼요.
SelectItem
value	string	필수
이 항목을 고르면 Select의 value가 이 값이 돼요.
disabled	boolean	false
SelectGroup
label	string	-
항목 위에 보이는 그룹 이름이에요.