Components

Select

Docs

Select API 사용가이드입니다. 조합 예시는 Overview를 참고하세요.

API

Select · SelectTrigger · SelectValue · SelectContent · SelectGroup · SelectLabel · SelectItem · SelectSeparator를 조합합니다. items 배열은 Root prop이 아니라 호출측에서 map해 SelectItem으로 렌더합니다.

import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectGroup,
  SelectItem,
} from "@/components/select";

const items = [
  { label: "Light", value: "light" },
  { label: "Dark", value: "dark" },
  { label: "System", value: "system" },
];

<Select>
  <SelectTrigger className="w-[180px]">
    <SelectValue placeholder="Theme" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      {items.map((item) => (
        <SelectItem key={item.value} value={item.value}>
          {item.label}
        </SelectItem>
      ))}
    </SelectGroup>
  </SelectContent>
</Select>

Props

Name	Type	Default	Description
`Select.value`	`string`	—	제어 모드 선택값. onValueChange와 함께 사용합니다.
`Select.defaultValue`	`string`	—	비제어 초기 선택값.
`Select.disabled`	`boolean`	—	전체 Select를 비활성화합니다.
`Select.name`	`string`	—	폼 제출 시 필드 키.
`SelectTrigger.icon`	`ReactNode \| null`	—	우측 아이콘. 생략 시 기본 chevron. 열리면 자동으로 회전합니다. ReactNode로 교체, null이면 숨김.
`SelectContent.side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	선호 열림 방향. position="popper"(기본)에서 공간이 부족하면 avoidCollisions로 위/아래가 자동 반전됩니다. 고정하려면 side를 지정하고 avoidCollisions={false}를 쓸 수 있습니다.
`SelectContent.avoidCollisions`	`boolean`	`true`	뷰포트 충돌 시 side를 자동 조정합니다. false면 side를 그대로 유지합니다.
`SelectValue.placeholder`	`string`	—	값이 없을 때 표시할 플레이스홀더.
`SelectItem.value`Required	`string`	—	옵션 값. 선택 시 Select.value와 매칭됩니다.
`SelectItem.disabled`	`boolean`	—	개별 옵션을 비활성화합니다.
`className`	`string`	—	각 파트의 추가 클래스. Trigger에 w-[180px] · w-full 등으로 너비를 제어합니다. Content는 Trigger 너비에 맞춰집니다.

Events

Name	Signature	Description
`Select.onValueChange`	`(value: string) => void`	선택값이 바뀔 때 호출됩니다.
`Select.onOpenChange`	`(open: boolean) => void`	드롭다운 열림/닫힘 상태가 바뀔 때 호출됩니다.

Notes

옵션 목록은 native가 아닙니다. SelectContent · SelectItem으로 커스텀 디자인합니다.
items는 Select Root prop이 아닙니다. 호출측 스코프에서 map해 children으로 전달하세요.
SelectGroup · SelectLabel · SelectSeparator로 옵션을 그룹·구분할 수 있습니다.
트리거 열림 시 chevron이 회전합니다 (data-state=open).
드롭다운은 기본적으로 아래(side="bottom")로 열리고, 공간이 없으면 위로 자동 반전됩니다. 강제하려면 side · avoidCollisions={false}.