Get StartedFoundationsComponentsPatternsRulesDevelopAI & ToolsUpdates

Select

옵션 목록에서 값을 골라 Form 에 제출할 때 사용하는 컴포넌트예요.

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/select.json

Anatomy

Select는 Trigger와 Content 두 부분으로 구성돼요. Content 안에는 Item이 놓이고, 관련 있는 Item은 Group으로 묶어요. Group 사이에는 Divider가 표시돼요.

  • Trigger: 현재 선택값 또는 Placeholder를 보여주고, 누르면 Content를 열어요. Suffix Icon의 Chevron이 Content가 열려 있는지 알려줘요. Prefix Icon은 선택적으로 둘 수 있어요.
  • Content: Trigger에 이어 표시되는 패널로, 옵션 목록을 펼쳐 보여줘요. 너비는 Trigger에 맞춰져요.
  • Item: Content 안의 옵션 하나예요. Item Label, Item Description, Prefix Icon으로 내용을 표현하고, Indicator로 선택 상태를 나타내요.
  • Group: 관련 있는 Item을 묶는 단위예요. Group Label로 제목을 붙일 수 있어요.
  • Divider: Group 사이에 자동으로 표시되는 구분선이에요. Item 사이에는 표시되지 않아요.
<SelectRoot defaultValue="apple">
  <SelectTrigger aria-label="과일" placeholder="과일 선택" />
  <SelectContent>
    <SelectGroup label="국산">
      <SelectItem value="apple" label="사과" />
      <SelectItem value="pear" label="배" />
    </SelectGroup>
  </SelectContent>
</SelectRoot>

이 문서에서 옵션은 목록에 둘 선택지 자체를, Item은 그 옵션을 Content에 그리는 UI 요소를, 선택값은 사용자가 고른 결과로 Form에 제출되는 데이터를 가리켜요.

Properties

Size

Large, Medium 두 가지 Size를 제공해요.

  • Large: 모바일·데스크톱 어디서나 사용할 수 있어요.
  • Medium: Breakpoint lg 이상(데스크톱)에서만 사용해요. 정밀한 선택이 가능한 마우스 입력 환경에서 더 작게 쓰고 싶을 때 골라요.
  • Responsive: lg 미만에서는 Large, 이상에서는 Medium으로 전환돼요. 같은 Form이 모바일과 데스크톱 양쪽에서 자연스럽게 동작해요.

State

Select의 상태는 Content의 열림 여부, 그리고 Trigger와 Item 각각의 State로 나뉘어요. Content가 열리면 Trigger의 Chevron이 180° 회전해요.

Trigger State

  • Enabled: 기본 상태예요.
  • Pressed: Trigger를 누르고 있는 동안의 상태예요.
  • Error: Form 검증 실패 상태예요. Trigger 테두리가 Critical 색으로 강조돼요. (invalid)
  • Disabled: 상호작용할 수 없는 상태예요. (disabled)
  • Read Only: 값을 보여주지만 바꿀 수 없는 상태예요. (readOnly)

Item State

  • Enabled, Pressed, Selected(Indicator에 Checkmark 표시), Disabled 상태를 가져요.

Group

관련 있는 Item을 SelectGroup 으로 묶어요. 모든 SelectItem 은 SelectGroup 안에 둬요. label 로 Group에 제목을 붙이고, Group 사이에는 Divider가 자동으로 표시돼요.

Item Description

Item Label에 부연 설명이 필요하면 description 을 사용해요. Item Description은 Trigger에 표시되지 않아요.

Has Prefix Icon

Trigger와 Item 왼쪽에 각각 Prefix Icon을 표시할 수 있어요. Trigger의 Prefix Icon은 어떤 종류의 값을 고르는 자리인지 아이콘으로 함께 알리고 싶을 때 사용해요.

Interaction

  • Trigger를 누르면: Content가 Trigger 아래에 표시돼요. 화면 아래쪽 공간이 부족하면 위쪽으로 자동 전환돼요.
  • Content가 열리면: 선택된 Item이 보이는 위치로 스크롤된 상태에서 열려요.
  • Item을 누르면: Trigger에 선택값이 표시되고 Content가 닫혀요.
  • Content 바깥을 누르면: Content가 닫혀요. 이미 선택된 값은 그대로 유지돼요.

Content Height

Content의 높이는 최대 480px과 Trigger 주변에 남은 화면 공간 중 더 작은 값으로 정해지고, 옵션이 더 많으면 Content 안에서 스크롤돼요.

Guidelines

Field의 Label과 함께 사용하기

Select는 항상 Field의 Label과 함께 사용해요. Label이 없으면 값을 고른 뒤에 그 값이 무엇을 나타내는지 알 수 없어요. Placeholder는 값을 고르면 사라지기 때문에 Label을 대신할 수 없어요.

단일 선택에서 "없음"을 답으로 받기

단일 선택 Select는 이미 고른 옵션을 다시 골라도 선택이 해제되지 않아요. 따라서 "없음"이 하나의 답이 될 수 있다면 그 답을 뜻하는 옵션을 목록에 둬요.

  • "없음"이 답이 될 수 있는 필드: "없음" 옵션을 목록에 둬요.
  • 하나를 반드시 골라야 하는 필드: "없음" 옵션 없이, 고르지 않은 상태로는 제출할 수 없게 해요. (예: 전화번호 국가 코드)
  • 고르지 않은 상태가 있을 수 없는 필드: "없음" 옵션 없이 기본값을 미리 선택해 둬요. (예: 정렬 기준)

"없음" 옵션의 Item Label은 질문의 핵심을 담아 써요. 예를 들어 Label이 "선호하는 과일"이라면 "해당 없음" 대신 "선호하는 과일 없음"이라고 써요. 이 옵션은 다른 옵션과 성격이 다르므로 목록 맨 앞이나 뒤에 별도 Group으로 둬요.

옵션 순서 정하기

목록 순서는 사용자가 옵션을 훑는 흐름에 맞춰요. 사용 빈도, 크기, 시간처럼 그 목록이 이미 가진 기준 하나를 골라 일관되게 정렬하고, 성격이 다른 옵션은 Group으로 묶어 경계를 드러내요.

Item Label 작성하기

Item Label은 한눈에 구분할 수 있도록 명사형으로 짧게 쓰고, Item 간에 어휘·길이·톤을 일관되게 유지해요. Trigger에서는 한 줄로 표시되어 너비를 넘으면 말줄임되니, 의도한 Label이 잘리지 않는지 확인해요.

강남구서초구송파구
Do· 명사형으로 짧게

지역 이름만 명사형으로 나열해요.

강남구 선택하기서초구 선택하기송파구 선택하기
Don't· 동작이나 부연 설명을 덧붙임

Item Label에 동작이나 부연 설명을 함께 적지 않아요.

Placeholder 작성하기

선택값이 없을 때 표시되는 Placeholder는 어떤 종류의 값을 고르는지 한눈에 알 수 있게 써요. Field의 Label이 있다면 Placeholder에 그 Label을 그대로 반복하지 않아요.

지역 선택
Do· 값의 종류를 알려줌

어떤 값을 고르는지 알 수 있게 써요.

여기를 눌러 펼쳐보기
Don't· 막연한 표현

어떤 값을 고르는지 알 수 없는 표현은 쓰지 않아요.

선택 컴포넌트 고르기

옵션마다 필요한 정보의 양, 옵션 개수, Item Label 길이에 따라 컴포넌트를 골라요.

  1. 옵션마다 이미지, 여러 줄 설명, Footer처럼 풍부한 정보가 필요하면 Select Box를 사용해요.
  2. 옵션이 5개 이상이거나 한 줄짜리 Item Description으로 충분하면 Select를 사용해요. 목록을 접어 두어 공간을 아낄 수 있어요.
  3. 옵션이 2~4개이고 설명이 필요 없으면 Label이 짧을 땐 Chip, 길 땐 Radio Group이나 Checkbox를 사용해요.

옵션이 아주 많아 스크롤만으로 탐색하기 어렵다면 검색형 선택(Combobox) 패턴을 고려해요.

Select vs. Menu

Menu는 동작을 실행하는 명령 목록이고, Select는 Form에 제출할 값을 고르는 입력 요소예요.

SelectMenu
목적Form에 제출할 값 고르기동작 실행하기
반영 시점고른 뒤 저장 또는 제출해야 반영됨Item을 누르면 즉시 실행됨
Field 조합Field와 함께 사용Field 조합 없음

Props

SelectRoot

Prop

Type

SelectTrigger

Prop

Type

SelectContent

Prop

Type

SelectGroup

Prop

Type

SelectItem

Prop

Type

On this page