Select

목록에서 고르는 컨트롤이다. 내부는 react-select 이지만 값은 옵션 객체가 아니라 원시값으로 주고받는다. 여러 개를 고르려면 MultiSelect 를 쓴다.

import { Select, MultiSelect } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Select } from "@nui-kit/react/select";
import "@nui-kit/react/styles/select.css";   // 온디맨드일 때

import { Select, MultiSelect } from "@nui-kit/react";

const OPTIONS = [
  { label: "서울", value: "seoul" },
  { label: "부산", value: "busan" },
];

<Select options={OPTIONS} value={city} onChange={setCity} />
<MultiSelect options={OPTIONS} value={cities} onChange={setCities} />

기본

값은 옵션 객체가 아니라 원시값(value) 으로 주고받는다. 폼 상태에 그대로 넣을 수 있다.

<Select options={OPTIONS} value={city} onChange={setCity} />

검색과 지우기

isSearchable 로 타이핑 필터를, isClearable 로 선택 해제 버튼을 켠다. 둘 다 기본값은 false 다.

<Select options={OPTIONS} isSearchable isClearable />

옵션 그룹

options={[{ label: "수도권", options: [{ label: "서울", value: "seoul" }] }]}

다중 선택

MultiSelect 는 값이 배열이다. 선택 항목은 칩으로 표시되고 칩의 × 로 개별 해제한다.

<MultiSelect options={OPTIONS} value={cities} onChange={setCities} />

상태

우선순위는 disabled > error > readonly 다. readOnly 는 값을 보여주되 메뉴를 열지 않는다 — disabled 와 달리 포커스는 받는다.

<Select options={OPTIONS} errorMessage="지역을 선택해주세요" />

Field 와 함께

Field 안에 넣으면 라벨의 htmlFor 와 컨트롤의 id, 설명·에러의 aria-describedby 가 자동으로 연결된다.

react-hook-form 연동

@nui-kit/react/rhf 의 RHFSelect · RHFMultiSelect 는 control 만 넘기면 값과 에러를 스스로 소유한다. value · onChange · name 은 타입에서 제외되어 있어 중복 소유가 생기지 않는다.

{
  "values": {
    "city": null,
    "interests": []
  },
  "isValid": false,
  "errors": {}
}

스타일 커스터마이징

컨트롤 외형은 공개 CSS 변수로 조정한다. 이 변수들은 라이브러리 레이어(@layer nui.components) 밖에서 선언하면 언제나 우선한다.

색은 컴포넌트별로 열지 않는다. 한 곳만 바꾸려면 className 을, 화면 전체를 바꾸려면 브랜드 프리셋을 쓴다.

// ❌ 렌더 안에서 컴포넌트를 새로 만든다
<Select components={{ Option: (props) => <CustomOption {...props} /> }} />

// ✅ 모듈 스코프에 한 번만 선언한다
const SELECT_COMPONENTS = { Option: CustomOption };
<Select components={SELECT_COMPONENTS} />

접근성

• Field 안에서는 라벨의 htmlFor 와 컨트롤의 id 가 자동으로 연결된다
• 설명·에러 메시지 id 는 aria-describedby 로 중복 없이 합쳐진다
• 에러일 때 aria-invalid 가 붙고, 메시지는 색이 아니라 아이콘 + 텍스트로 표시된다
• 키보드로 조작한다 — ↑ ↓ 로 이동, Enter 로 선택, Esc 로 닫기
• readOnly 는 포커스는 받되 메뉴를 열지 않는다. disabled 는 포커스 자체를 받지 않는다
• MultiSelect 칩의 × 는 Tab 으로 닿는 버튼이다. 칩이 여럿이면 앞에서부터 하나씩 잡히고, 그다음이 입력창이다. Enter 와 Space 로 지운다. 지우고 나면 포커스가 이전 칩으로, 없으면 입력창으로 간다
• 칩 × 의 접근 이름은 기본 "서울 옵션 삭제" 이고 removeButtonLabel 로 바꾼다. 라벨을 끼워 넣는 자리가 언어마다 달라서 문자열이 아니라 함수를 받는다

  <MultiSelect removeButtonLabel={(label) => `Remove ${label}`} />

API

아래 표는 이 라이브러리가 정의한 prop 이다. 여기에 없는 react-select 의 prop(menuPlacement, maxMenuHeight, closeMenuOnSelect 등)도 그대로 전달된다. 단 defaultValue(controlled 전용), getOptionValue(원시값 매칭이 value 고정), theme(unstyled 라 효과 없음) 은 받지 않는다.

Select

SelectProps 에서 자동 생성됨 (components/Select/Select.tsx). 표준 DOM 속성 58개는 그대로 전달되며 표에서 생략했다.

MultiSelect

MultiSelectProps 에서 자동 생성됨 (components/Select/MultiSelect.tsx). 표준 DOM 속성 58개는 그대로 전달되며 표에서 생략했다.