Project Information

Select / MultiSelect / RHFSelect / RHFMultiSelect

react-select 기반 Select, MultiSelect, RHFSelect, RHFMultiSelect의 controlled usage, React Hook Form 연동, props 확장 패턴을 정리한 가이드 페이지입니다.

Select

Select / controlled usage

Select는 react-select를 기반으로 value와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 선택 컴포넌트입니다.

Prop

value | onChange | options

value: string | number | nulloptions: OptionsOrGroups<SelectOption, GroupBase<SelectOption>>

Select는 단일 선택 전용 래퍼입니다. react-select의 option 객체는 내부에서만 쓰고, 외부에서는 선택된 value 하나만 주고받습니다. options는 일반 목록과 grouped options를 모두 그대로 전달할 수 있습니다.

카테고리

디자인

Prop

isSearchable | isClearable | placeholder

boolean | string

react-select의 검색과 clear 기능을 그대로 열어두되, 기본 스타일은 Textfield와 유사한 형태로 맞췄습니다.

담당자

담당자를 선택해주세요

Prop

MultiSelect

value: (string | number)[]

MultiSelect는 다중 선택 전용 래퍼입니다. value는 항상 배열로 관리되고, 여러 option을 chip 형태로 선택할 수 있습니다.

기술 스택

React

TypeScript

Prop

disabled | readOnly | isError | grouped options

boolean | OptionsOrGroups<SelectOption, GroupBase<SelectOption>>

disabled는 상호작용 전체를 막고, readOnly는 현재 값을 유지한 채 메뉴 열기, 검색, clear, 값 변경만 막습니다. grouped options는 Select와 MultiSelect 모두 그대로 전달할 수 있습니다.

disabled 상태

운영

readOnly 상태

에디터

isError 상태

항목을 선택해주세요

항목을 선택해주세요.

React Hook Form

RHFSelect / RHFMultiSelect / 폼 연동

RHFSelect는 단일 선택, RHFMultiSelect는 다중 선택을 React Hook Form 필드와 연결한 래퍼 컴포넌트입니다.

Prop

Select props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, SelectProps, RHFValueInputManagedProps>

RHFSelect는 Select props를 기반으로 하고, name/value/defaultValue/onBlur/onChange는 RHF가 관리합니다. 단일 선택값은 string | number | null 형태로 RHF 상태와 연결되고, defaultValue도 null 또는 단일 value 형태를 사용합니다.

Prop

rules

required | validate

필수 선택처럼 단일 선택값이 반드시 있어야 하는 경우 rules로 검증을 연결할 수 있습니다.

Prop

RHFMultiSelect

RHFComponentProps<TFormValues, TFieldName, MultiSelectProps, RHFValueInputManagedProps>

RHFMultiSelect는 다중 선택 전용 래퍼입니다. RHF 필드는 배열 값을 다루고, defaultValue도 [] 같은 배열 형태를 사용하는 것이 자연스럽습니다. closeMenuOnSelect={false} 조합도 자주 함께 사용합니다.

Prop

react-select props

isSearchable | isClearable | noOptionsMessage | menuPlacement ...

RHF 연결과 함께 react-select 주요 props를 그대로 함께 전달할 수 있습니다. isSearchable, isClearable, noOptionsMessage, menuPlacement뿐 아니라 styles, components 같은 확장도 동일하게 사용할 수 있습니다.

Props Table

Select props 한눈에 보기

Select의 단일 선택 value 규칙과 react-select 확장 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`options`	`OptionsOrGroups<SelectOption, GroupBase<SelectOption>>`	-	Required	일반 옵션 목록과 grouped options를 모두 그대로 전달할 수 있습니다.
`value`	`string \| number \| null`	`null`	Optional	외부에서는 option 객체 대신 선택된 primitive value 하나만 주고받습니다.
`onChange`	`(nextValue, selectedOption, actionMeta) => void`	`undefined`	Optional	nextValue는 primitive value 또는 null이고, selectedOption과 actionMeta도 함께 받을 수 있습니다.
`placeholder`	`string`	`"항목을 선택해주세요"`	Optional	선택값이 없을 때 표시할 안내 문구입니다.
`disabled`	`boolean`	`false`	Optional	상호작용 전체를 비활성화합니다.
`readOnly`	`boolean`	`false`	Optional	현재 값을 유지한 채 메뉴 열기, 검색, clear, 값 변경만 막습니다.
`isError`	`boolean`	`false`	Optional	시각 에러 상태와 aria-invalid를 적용합니다. Field의 에러 상태와 합쳐집니다.
`infoMessage \| errorMessage`	`string`	`""`	Optional	필드 아래에 안내 메시지나 에러 메시지를 노출합니다.
`isSearchable \| isClearable`	`boolean`	`false \| false`	Optional	react-select 검색과 clear 기능을 그대로 열어둡니다. readOnly/disabled에서는 자동으로 비활성화됩니다.
`components \| styles`	`react-select extension props`	`undefined`	Optional	react-select 커스텀 컴포넌트와 스타일 확장을 전달할 수 있습니다.
`menuPlacement \| menuPosition \| noOptionsMessage ...`	`react-select props`	`inherited`	Optional	react-select의 주요 메뉴 제어 prop도 함께 전달할 수 있습니다.

SelectProps는 react-select의 단일 선택 API를 감싸되, 외부에서는 option 객체 대신 primitive value만 다루도록 단순화한 래퍼 타입입니다.

Props Table

MultiSelect props 한눈에 보기

MultiSelect의 다중 선택 value 규칙과 자주 쓰는 react-select props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`options`	`OptionsOrGroups<SelectOption, GroupBase<SelectOption>>`	-	Required	일반 옵션 목록과 grouped options를 모두 그대로 전달할 수 있습니다.
`value`	`(string \| number)[]`	`[]`	Optional	외부에서는 선택된 primitive value 배열만 주고받습니다.
`onChange`	`(nextValue, selectedOption, actionMeta) => void`	`undefined`	Optional	nextValue는 primitive value 배열이고, selectedOption과 actionMeta도 함께 받을 수 있습니다.
`closeMenuOnSelect`	`boolean`	`react-select default`	Optional	다중 선택에서는 보통 false로 두고 연속 선택 흐름을 만듭니다.
`isSearchable \| isClearable`	`boolean`	`false \| false`	Optional	검색과 전체 clear 기능을 그대로 열어둘 수 있습니다. readOnly/disabled에서는 자동으로 비활성화됩니다.
`placeholder`	`string`	`"항목을 선택해주세요"`	Optional	선택값이 없을 때 표시할 안내 문구입니다.
`disabled \| readOnly \| isError`	`boolean`	`false`	Optional	상태 제어와 에러 표시 규칙은 Select와 동일합니다.
`infoMessage \| errorMessage`	`string`	`""`	Optional	필드 아래에 안내 메시지나 에러 메시지를 노출합니다.
`components \| styles \| menuPlacement ...`	`react-select props`	`inherited`	Optional	react-select의 커스텀 컴포넌트, 스타일, 메뉴 제어 prop도 함께 전달할 수 있습니다.

MultiSelectProps는 react-select의 다중 선택 API를 감싸되, 외부에서는 option 객체 대신 primitive value[]만 다루도록 단순화한 래퍼 타입입니다.

Props Table

RHFSelect props 한눈에 보기

RHFSelect에서 사용하는 RHF 제어 props와 Select 상속 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`UseControllerProps['rules']`	`undefined`	Optional	필수 선택이나 커스텀 검증 규칙을 useController 규격으로 전달합니다.
`defaultValue`	`string \| number \| null`	`undefined`	Optional	일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 Select에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`isError \| errorMessage`	`boolean \| string`	`false \| field error message`	Optional	RHF 검증 상태를 기반으로 시각 에러 상태와 메시지를 적용합니다.
`options \| isSearchable \| isClearable ...`	`Select inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Select UI props와 react-select props는 그대로 전달할 수 있습니다.

RHFSelectProps는 SelectProps에서 name, value, defaultValue, onBlur, onChange를 RHF가 관리하는 구조입니다.

Props Table

RHFMultiSelect props 한눈에 보기

RHFMultiSelect에서 사용하는 RHF 제어 props와 MultiSelect 상속 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`UseControllerProps['rules']`	`undefined`	Optional	최소 선택 개수 같은 검증 규칙을 useController 규격으로 전달합니다.
`defaultValue`	`(string \| number)[]`	`undefined`	Optional	일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 MultiSelect에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`isError \| errorMessage`	`boolean \| string`	`false \| field error message`	Optional	RHF 검증 상태를 기반으로 시각 에러 상태와 메시지를 적용합니다.
`options \| closeMenuOnSelect \| isSearchable ...`	`MultiSelect inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 MultiSelect UI props와 react-select props는 그대로 전달할 수 있습니다.

RHFMultiSelectProps는 MultiSelectProps에서 name, value, defaultValue, onBlur, onChange를 RHF가 관리하는 구조입니다.