Project Information

DateMultiplePicker / RHFDateMultiplePicker

controlled usage와 React Hook Form 연동 기준으로 DateMultiplePicker와 RHFDateMultiplePicker의 주요 props와 사용 패턴을 정리한 가이드 페이지입니다.

DateMultiplePicker

DateMultiplePicker / controlled usage

DateMultiplePicker는 selected와 onSelectedChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 복수 날짜 선택 컴포넌트입니다. 여러 날짜를 배열 형태로 관리합니다.

Prop

Textfield props 확장

Omit<TextfieldProps, "children" | "isTextInputBlocked" | "onChange" | "type" | "value"> & { selected?: Date[]; onSelectedChange?: (selected?: Date[]) => void; dayPickerProps?: PropsMulti | PropsMultiRequired; ... }

- DateMultiplePicker는 복수 날짜 선택을 위한 Textfield 기반 래퍼입니다.
- placeholder, infoMessage, errorMessage, readOnly, disabled, isClearable, onClear 같은 Textfield props를 그대로 사용할 수 있고, selected는 Date[] 형태로 제어합니다.
- dayPickerProps에는 복수 선택 모드에 맞는 min, max, required 같은 옵션을 전달할 수 있습니다.
- defaultIsCalendarOpen, getDefaultMonth, getShouldCloseOnSelect 같은 캘린더 제어 props도 함께 사용할 수 있습니다.

여러 날짜를 태그처럼 선택해야 하는 예약/스케줄 UX에 사용할 수 있습니다.

Prop

selected | onSelectedChange

Date[] | undefined

복수 선택 모드는 선택된 날짜 배열을 외부에서 제어합니다.

선택된 날짜 수: 3개

Prop

isClearable | onClear

boolean | () => void

clear 버튼은 isClearable이 true이고, selected 값이 있으며, dayPickerProps.required/readOnly/disabled가 아닐 때만 노출됩니다. 클릭하면 onSelectedChange(undefined)가 먼저 호출되고, onClear를 전달했다면 그 다음 실행됩니다.

초기 선택값 유지 / clear 버튼으로 복수 선택 값을 비울 수 있습니다.

Prop

dayPickerProps

PropsMulti | PropsMultiRequired

복수 선택 모드에서는 min, max, required, disabled 같은 옵션을 많이 사용합니다.

최대 4개까지 선택하고, 일요일은 disabled 처리한 예시입니다.

required 복수 선택은 clear 버튼이 숨겨지고 최소 선택 개수를 유지합니다.

Prop

displayFormat | formatDisplayValue

string | ({ displayFormat, locale, selected }) => string

복수 날짜 배열을 입력창에 어떻게 표시할지 커스터마이징할 수 있습니다.

Prop

defaultIsCalendarOpen | shouldCloseOnSelect | calendarButtonTitle | dropdownClassName

boolean | string

복수 선택 모드는 기본적으로 선택 후 닫히지 않습니다. defaultIsCalendarOpen으로 초기 렌더에서 열어둘 수 있고, shouldCloseOnSelect를 true로 넘기면 선택할 때마다 캘린더를 닫도록 바꿀 수 있습니다. calendarButtonTitle과 dropdownClassName으로 캘린더 버튼/래퍼도 제어할 수 있습니다.

복수 선택 모드의 기본 닫힘 동작은 false이며, defaultIsCalendarOpen으로 처음부터 열어둘 수 있습니다.

2026년 3월

shouldCloseOnSelect=true로 선택할 때마다 캘린더를 닫는 예시입니다.

Prop

getDefaultMonth | getShouldCloseOnSelect

({ selected }) => Date | undefined | ({ shouldCloseOnSelect, nextSelected }) => boolean

getDefaultMonth는 선택값이 없을 때 처음 보여줄 월을 계산하고, getShouldCloseOnSelect는 복수 선택 중 캘린더를 닫을지 직접 결정합니다.

selected가 없으면 2026년 7월부터 시작하도록 기본 월을 커스터마이징한 예시입니다.

2026년 7월

3개 미만을 선택하면 캘린더를 유지하고, 3개 이상 선택하면 닫히도록 제어한 예시입니다.

Prop

disabled | readOnly

boolean

default: false

DateMultiplePicker도 기본적으로 직접 타이핑 입력이 막혀 있고, disabled는 전체 상호작용을 비활성화합니다. readOnly는 현재 선택만 표시하면서 캘린더 열기, 날짜 변경, clear 버튼을 막습니다.

readOnly 상태에서는 현재 선택만 표시되고 캘린더 선택과 clear가 막힙니다.

React Hook Form

RHFDateMultiplePicker / 폼 연동

RHFDateMultiplePicker는 DateMultiplePicker props를 유지하면서 Date[] 필드를 React Hook Form에 연결한 래퍼 컴포넌트입니다.

Prop

DateMultiplePicker props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, DateMultiplePickerProps, "selected">

RHFDateMultiplePicker는 DateMultiplePicker props를 기반으로 하고, "selected" 값은 RHF field.value로 관리합니다. name/control/rules/defaultValue/shouldUnregister/disabled는 RHF가 관리하고, 나머지 DateMultiplePicker UI props와 캘린더 제어 props는 그대로 사용할 수 있습니다. clear 버튼을 사용하면 RHF 값이 먼저 undefined로 정리된 뒤 onClear를 전달했다면 그 다음 호출됩니다.

Prop

rules

validate ...

복수 선택 필드는 선택 개수 조건을 validate로 검사하는 패턴이 자주 사용됩니다.

Prop

dayPickerProps

PropsMulti | PropsMultiRequired

required, min, max, disabled 같은 복수 선택 옵션을 RHF 상태와 함께 사용할 수 있습니다.

Prop

displayFormat | formatDisplayValue | shouldCloseOnSelect

string | ({ displayFormat, locale, selected }) => string | boolean

복수 선택 모드도 DatepickerBase의 공통 표시 포맷/닫힘 제어 props를 그대로 사용할 수 있습니다.

Prop

disabled | readOnly

boolean

RHFDateMultiplePicker도 DateMultiplePicker 상태 props를 그대로 상속합니다. disabled는 RHF controller와 UI를 함께 비활성화하고, readOnly는 현재 선택만 표시하면서 캘린더 열기, 날짜 변경, clear를 막습니다.

disabled 복수 날짜

disabled는 RHF field와 UI를 함께 비활성화합니다.

readOnly 복수 날짜

readOnly 상태에서는 현재 선택만 표시되고 캘린더와 clear 버튼이 비활성화됩니다.

Prop

defaultIsCalendarOpen | shouldCloseOnSelect | calendarButtonTitle | dropdownClassName

boolean | string

RHF 연결 상태에서도 캘린더 열림/닫힘 관련 props를 그대로 사용할 수 있습니다. defaultIsCalendarOpen은 내부 상태의 초기값이고, shouldCloseOnSelect=true로 선택 시마다 닫히도록 바꿀 수 있습니다. calendarButtonTitle과 dropdownClassName도 동일하게 전달됩니다.

초기 열림 RHF 복수 선택 캘린더

defaultIsCalendarOpen, calendarButtonTitle, dropdownClassName을 함께 사용한 RHF 예시입니다.

2026년 3월

선택 시 닫히는 RHF 복수 선택 캘린더

shouldCloseOnSelect=true로 선택할 때마다 닫히는 RHF 예시입니다.

Prop

getDefaultMonth | getShouldCloseOnSelect

({ selected }) => Date | undefined | ({ shouldCloseOnSelect, nextSelected }) => boolean

RHF 연결 상태에서도 getDefaultMonth와 getShouldCloseOnSelect를 그대로 사용할 수 있습니다. 선택값이 없을 때 처음 보여줄 월을 계산하거나, 복수 선택 중 닫힘 조건을 직접 커스터마이징할 때 사용합니다.

기본 월 커스텀

selected가 없으면 2026년 7월부터 시작하도록 기본 월을 커스터마이징한 RHF 예시입니다.

2026년 7월

닫힘 조건 커스텀

3개 미만을 선택하면 캘린더를 유지하고, 3개 이상 선택하면 닫히도록 제어한 RHF 예시입니다.

Props Table

DateMultiplePicker props 한눈에 보기

복수 날짜 선택 동작과 Textfield 상속 규칙을 함께 정리했습니다.

Prop	Type	Default	Required	Description
`selected`	`Date[] \| undefined`	`undefined`	Optional	현재 선택된 날짜 배열입니다.
`onSelectedChange`	`(selected: Date[] \| undefined) => void`	`undefined`	Optional	날짜를 추가/제거한 뒤 최종 선택 배열을 외부 상태에 반영하는 콜백입니다.
`dayPickerProps`	`PropsMulti \| PropsMultiRequired`	`undefined`	Optional	복수 선택용 DayPicker 옵션을 전달합니다. min, max, required, disabled 같은 제약도 여기서 설정합니다.
`displayFormat`	`string`	`"yyyy.MM.dd"`	Optional	기본 formatDisplayValue가 각 날짜를 input 문자열로 표시할 때 사용하는 포맷입니다.
`formatDisplayValue`	`({ displayFormat, locale, selected }) => string`	`formatMultipleDateValue`	Optional	기본 구현은 날짜 배열을 displayFormat 기준으로 포맷한 뒤 `, `로 이어 붙입니다.
`getDefaultMonth`	`({ selected }) => Date \| undefined`	`selected?.[0]`	Optional	캘린더 기본 월을 첫 번째 선택 날짜 기준으로 계산합니다.
`shouldCloseOnSelect \| getShouldCloseOnSelect`	`boolean \| ({ shouldCloseOnSelect, nextSelected }) => boolean`	`false`	Optional	명시하지 않으면 날짜를 선택해도 캘린더가 닫히지 않고, boolean 또는 함수로 닫힘 전략을 바꿀 수 있습니다.
`defaultIsCalendarOpen \| calendarButtonTitle \| dropdownClassName`	`boolean \| string`	`false \| auto title \| undefined`	Optional	초기 열림 상태와 우측 캘린더 버튼 title, dropdown wrapper 클래스명을 함께 제어합니다.
`placeholder \| infoMessage \| errorMessage \| isClearable \| onClear`	`Textfield inherited props`	`inherited`	Optional	Textfield의 입력 표시, 메시지, clear UI 규칙을 그대로 상속합니다. required/readOnly/disabled에서는 clear 버튼이 숨겨집니다.
`id \| name \| autoComplete \| aria-* ...`	`native input props`	`inherited`	Optional	DatepickerBase가 직접 제어하지 않는 native input props는 내부 input에 그대로 전달됩니다.

DateMultiplePickerProps는 DatepickerBaseProps<Date[], PropsMulti | PropsMultiRequired>기반이고, 기본 표시 구현은 선택된 날짜 배열을 문자열로 이어 붙여 input에 보여줍니다.

Props Table

RHFDateMultiplePicker props 한눈에 보기

RHFDateMultiplePicker에서 사용하는 RHF 제어 props와 DateMultiplePicker 상속 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`	`Date[] \| undefined`	`undefined`	Optional	필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 DateMultiplePicker에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`errorMessage`	`string`	`field error message`	Optional	RHF 검증 메시지가 없을 때만 fallback 에러 메시지로 사용됩니다.
`onSelectedChange`	`(selected: Date[] \| undefined) => void`	`undefined`	Optional	field.onChange 이후 추가로 호출되므로 선택 배열 변화에 맞춘 부수효과를 연결할 때 사용합니다.
`dayPickerProps \| displayFormat \| shouldCloseOnSelect ...`	`DateMultiplePicker inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 복수 선택 UI props와 캘린더 제어 props는 그대로 전달할 수 있습니다.

RHFDateMultiplePickerProps는 DateMultiplePickerProps에 RHF 제어 prop을 합친 구조입니다. 실제 selected 배열은 RHF field state가 관리하고, 나머지 날짜 표시/캘린더 동작 prop만 직접 전달합니다.

일	월	화	수	목	금	토

일	월	화	수	목	금	토

일	월	화	수	목	금	토

일	월	화	수	목	금	토