Get startedFoundationsComponentsPatternsRules

Select

셀렉트는 목록에서 하나 또는 여러 항목을 고르게 해요.

설치

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

Examples

Single select

기본은 하나만 고르는 셀렉트예요. 고른 옵션은 입력 영역에 보이고, 입력하면 옵션이 걸러져요.

Single select clearable

isClearable 을 켜면 선택값 오른쪽에 지우기 버튼이 생겨요. 키보드로는 입력이 비어 있을 때 Backspace 나 Delete 로 지울 수 있어요.

Multi select

isMulti 를 켜면 여러 개를 고를 수 있어요. 고른 값은 태그로 보이고, 태그의 x 로 하나씩 지우거나 지우기 버튼으로 한 번에 비울 수 있어요. 이미 고른 옵션은 메뉴에서 숨겨져요 (hideSelectedOptions).

Checkbox select

CheckboxSelect 는 옵션마다 체크박스가 붙는 다중 선택이에요. 옵션을 골라도 메뉴가 닫히지 않고, 고른 옵션도 목록에 남아 체크 표시로 보여요. 키보드나 마우스로 옮겨 간 옵션은 background.neutral.subtle.hovered 배경으로만 표시하고, 일반 Select 와 달리 왼쪽 2px 막대는 그리지 않아요.

Radio select

RadioSelect 는 옵션마다 라디오 버튼이 붙는 단일 선택이에요. 고른 옵션이 메뉴 안에서 바로 보여서, 우선순위처럼 하나를 고르면서 다른 선택지와 견주어 볼 때 좋아요.

Grouped options

options 에 { label, options } 형태의 그룹을 넣으면 그룹 제목과 함께 묶여 보여요. 옵션에 isDisabled: true 를 주면 고를 수 없어요.

Searchable

isSearchable 은 기본으로 켜져 있어요. 옵션이 몇 개 안 되면 isSearchable={false} 로 입력 없이 고르게 할 수 있어요.

Appearance

subtle 은 평소에는 배경과 테두리가 없다가, 마우스를 올리거나 포커스하면 필드 모양이 드러나요. 표나 상세 화면 안에서 값을 바로 바꾸는 곳에 어울려요.

Appearance용도
default폼 안의 일반적인 선택 필드
subtle주변 내용과 섞여 보여야 하는 인라인 편집
none테두리·배경이 전혀 없는 커스텀 컨테이너 안

Spacing

compact 는 높이 32px 이에요. 필터 바처럼 정보 밀도가 높은 곳에 써요.

States

isInvalid 는 오류 테두리를, isLoading 은 옵션을 불러오는 동안 스피너를, isDisabled 는 비활성 상태를 보여줘요. 오류 문구는 descriptionId 로 연결해요.

Controlled

value 와 onChange 로 값을 직접 관리할 수 있어요. 다중 선택에서 closeMenuOnSelect={false} 를 주면 여러 개를 연달아 고를 수 있어요.

Usage guidelines

셀렉트는 목록에서 하나 이상의 항목을 고를 때 써요. 주로 폼이나 인라인 편집 안에서 쓰여요.

  • 바로 실행되는 액션 목록이 필요하면 Dropdown menu 를 써요.
  • 즉시 켜고 끄는 설정은 Toggle, 저장 버튼으로 적용하는 여러 설정은 Checkbox, 몇 개 안 되는 선택지 중 하나는 Radio 가 더 나아요.

구성

  • 단일 선택: 필드 라벨, 입력 영역, 메뉴로 이루어져요. 고른 옵션이 입력 영역에 표시돼요.
  • 다중 선택: 여기에 선택값 태그(각각 x 로 제거)와 전체 지우기 버튼이 더해져요. 전체 지우기는 하나 이상 골랐을 때만 보여요.

옵션 정리하기

  • 자주 고르는 순서나 숫자 순서처럼 의미 있는 순서로 늘어놓아요. 가나다순은 언어마다 순서가 달라져서 피하는 편이 좋아요.
  • 옵션이 너무 많으면 고르기 어려워요. 꼭 필요한 것만 남겨요.
  • 그룹은 아껴서 써요. 일부만 그룹으로 묶으면 그룹의 의미가 흐려지니 모두 묶거나 아예 묶지 않아요. 옵션이 하나뿐인 그룹은 만들지 않아요.
  • 그룹은 누구나 아는 분류이거나, 이름이 비슷한 옵션을 구분해야 할 때만 써요.
Do· 라벨과 도움말
필드 라벨과 도움말로 무엇을 골라야 하는지 알려줘요.
Don't· placeholder 를 라벨처럼
placeholder 는 값을 고르면 사라져서 라벨을 대신할 수 없어요.

문구

  • 라벨은 짧고 목적이 분명하게 써요. (예: "담당자", "스프린트")
  • 옵션 하나는 한 줄에 들어가게 써요.
  • 누구나 아는 쉽고 직접적인 단어를 써요.

Accessibility

  • 입력 요소는 role="combobox" 이고 메뉴는 role="listbox" 예요. 키보드로 옮겨 다니는 옵션은 aria-activedescendant 로 알려서, 포커스는 입력에 머문 채 스크린 리더가 현재 옵션을 읽어요.
  • 라벨은 필드 밖에 두고 <label htmlFor> 와 inputId 로 연결해요. 라벨이 보이지 않는 곳이라면 aria-label 을 지정해요.
  • 지우기 버튼은 탭 순서에서 빠져 있어요. 탭 이동 횟수를 줄이기 위해서이고, 키보드로는 Backspace·Delete 로 지울 수 있어요.
키동작
↓ / ↑메뉴를 열거나 다음·이전 옵션으로 이동
Home / End첫 옵션·마지막 옵션으로 이동
Enter포커스된 옵션 선택
Space입력이 비어 있으면 메뉴 열기 또는 옵션 선택
Esc메뉴 닫기 (닫혀 있고 isClearable 이면 값 지우기)
Backspace / Delete입력이 비어 있을 때 마지막 선택값 제거
Tab메뉴를 닫고 다음 요소로 이동

Props

Prop

Type

CheckboxSelect 와 RadioSelect 는 isMulti 를 뺀 같은 props 를 받아요. CheckboxSelect 는 isMulti·closeMenuOnSelect={false}·hideSelectedOptions={false} 가 기본이고, RadioSelect 는 항상 단일 선택이에요.

On this page