Project Information

Datepicker / RHFDatepicker

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

Datepicker

Datepicker / controlled usage

Datepicker는 selected와 onSelectedChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 단일 날짜 선택 컴포넌트입니다. Textfield 기반 캘린더 입력 패턴으로 구성됩니다.

Prop

Textfield props 확장

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

- Datepicker는 Textfield props를 확장한 단일 날짜 선택 컴포넌트입니다.
- placeholder, infoMessage, errorMessage, isClearable, onClear, readOnly, disabled 같은 Textfield props를 그대로 사용할 수 있습니다.
- selected와 onSelectedChange로 날짜를 제어하고, dayPickerProps로 react-day-picker 옵션을 전달합니다.
- defaultIsCalendarOpen, getDefaultMonth, getShouldCloseOnSelect 같은 캘린더 제어 props도 함께 사용할 수 있습니다.

Textfield props를 유지한 채 단일 날짜 선택 UI를 제공합니다.

Prop

selected | onSelectedChange

Date | undefined

선택된 날짜와 변경 핸들러를 외부에서 제어하는 상태 제어 패턴입니다.

선택된 날짜: 2026.03.20

Prop

isClearable | onClear

boolean | () => void

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

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

Prop

displayFormat | formatDisplayValue

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

입력창에 표시할 날짜 문자열 포맷을 제어합니다. formatDisplayValue를 사용하면 displayFormat보다 더 자유롭게 표시 텍스트를 바꿀 수 있습니다.

Prop

dayPickerProps

PropsSingle | PropsSingleRequired

dayPickerProps로 DayPicker 선택 props와 기본 옵션을 함께 전달할 수 있습니다.
아래 예시는 startMonth, endMonth, disabled, required를 사용하는 경우입니다.

2026년 2월 안에서만 선택할 수 있습니다.

주말은 disabled 처리한 예시입니다.

required일 때는 clear 버튼이 노출되지 않습니다.

Prop

defaultIsCalendarOpen | shouldCloseOnSelect | calendarButtonTitle | dropdownClassName

boolean | string

defaultIsCalendarOpen은 내부 열림 상태의 초기값입니다. shouldCloseOnSelect를 false로 두면 단일 날짜 선택 후에도 캘린더를 유지할 수 있고, calendarButtonTitle과 dropdownClassName으로 버튼 title과 캘린더 래퍼를 제어할 수 있습니다.

defaultIsCalendarOpen과 dropdownClassName을 함께 사용한 예시입니다.

2026년 3월

shouldCloseOnSelect=false로 선택 후에도 캘린더를 유지합니다.

Prop

getDefaultMonth | getShouldCloseOnSelect

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

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

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

2026년 7월

15일 미만 날짜를 선택하면 캘린더를 유지하고, 15일 이후 날짜를 선택하면 닫히도록 제어한 예시입니다.

Prop

disabled | readOnly

boolean

default: false

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

disabled 상태 예시

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

React Hook Form

RHFDatepicker / 폼 연동

RHFDatepicker는 Datepicker props를 유지하면서 useController로 단일 날짜 필드를 React Hook Form에 연결한 래퍼 컴포넌트입니다.

Prop

Datepicker props 확장 + RHFComponentProps

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

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

Prop

rules

required | validate ...

날짜 필드도 RHF rules로 검증할 수 있습니다. 아래 예시는 선택하지 않은 상태로 제출하면 에러를 보여줍니다.

Prop

dayPickerProps

PropsSingle | PropsSingleRequired

RHF 연결 상태에서도 dayPickerProps를 그대로 전달할 수 있습니다. required, startMonth, endMonth, disabled 같은 DayPicker 옵션을 함께 사용할 수 있습니다.

Prop

displayFormat | formatDisplayValue | shouldCloseOnSelect

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

Datepicker에서 제공하는 표시 포맷과 캘린더 동작 props도 RHFDatepicker에서 그대로 사용할 수 있습니다.

Prop

disabled | readOnly

boolean

RHFDatepicker도 Datepicker 상태 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=false로 선택 후에도 캘린더를 유지할 수 있습니다. dropdownClassName은 실제 열리는 캘린더 래퍼에 class를 추가합니다.

초기 열림 RHF 캘린더

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

2026년 3월

선택 후 유지 RHF 캘린더

shouldCloseOnSelect=false로 선택 후에도 캘린더를 유지하는 RHF 예시입니다.

Prop

getDefaultMonth | getShouldCloseOnSelect

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

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

기본 월 커스텀

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

2026년 7월

닫힘 조건 커스텀

15일 미만 날짜를 선택하면 캘린더를 유지하고, 15일 이후 날짜를 선택하면 닫히도록 제어한 RHF 예시입니다.

Props Table

Datepicker props 한눈에 보기

단일 날짜 선택에 필요한 핵심 props와 Textfield 상속 규칙을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`selected`	`Date \| undefined`	`undefined`	Optional	현재 선택된 단일 날짜 값입니다.
`onSelectedChange`	`(selected: Date \| undefined) => void`	`undefined`	Optional	캘린더 선택이나 clear 이후 최종 선택값을 외부 상태에 반영하는 콜백입니다.
`dayPickerProps`	`PropsSingle \| PropsSingleRequired`	`undefined`	Optional	react-day-picker 단일 선택 옵션을 전달합니다. required, disabled, startMonth, endMonth 같은 제한도 여기서 제어합니다.
`displayFormat`	`string`	`"yyyy.MM.dd"`	Optional	기본 formatDisplayValue가 input에 표시할 날짜 문자열 포맷입니다.
`formatDisplayValue`	`({ displayFormat, locale, selected }) => string`	`formatSingleDateValue`	Optional	displayFormat보다 더 세밀하게 입력창 표시 문자열을 커스터마이징합니다.
`getDefaultMonth`	`({ selected }) => Date \| undefined`	`selected`	Optional	캘린더를 처음 열 때 어떤 월을 보여줄지 계산하는 전략 함수입니다.
`shouldCloseOnSelect \| getShouldCloseOnSelect`	`boolean \| ({ shouldCloseOnSelect, nextSelected }) => boolean`	`auto close on selected date`	Optional	명시하지 않으면 날짜를 하나 선택한 뒤 자동으로 닫히고, boolean 또는 함수로 닫힘 규칙을 덮어쓸 수 있습니다.
`defaultIsCalendarOpen`	`boolean`	`false`	Optional	초기 렌더에서 캘린더 dropdown을 열어둘지 결정합니다.
`calendarButtonTitle \| dropdownClassName`	`string`	`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에 그대로 전달됩니다.

DatepickerProps는 DatepickerBaseProps<Date, PropsSingle | PropsSingleRequired>에서 내부 전략 prop인 mode와 기본 구현 함수를 optional override 형태로 다시 노출한 타입입니다.

Props Table

RHFDatepicker props 한눈에 보기

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

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`UseControllerProps['rules']`	`undefined`	Optional	required, validate 같은 날짜 검증 규칙을 useController 규격으로 전달합니다.
`defaultValue`	`Date \| undefined`	`undefined`	Optional	필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 Datepicker에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`errorMessage`	`string`	`field error message`	Optional	RHF 검증 메시지가 없을 때만 fallback 에러 메시지로 사용됩니다.
`onSelectedChange`	`(selected: Date \| undefined) => void`	`undefined`	Optional	field.onChange 이후 추가로 호출되므로 RHF 상태와 함께 부수효과를 연결할 때 사용합니다.
`dayPickerProps \| displayFormat \| shouldCloseOnSelect ...`	`Datepicker inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Datepicker UI props와 캘린더 제어 props는 그대로 전달할 수 있습니다.

RHFDatepickerProps는 DatepickerProps에 RHF의 name, control, rules, defaultValue, shouldUnregister를 합친 구조이고, 실제 selected 값은 RHF field state가 직접 관리합니다.

일	월	화	수	목	금	토

일	월	화	수	목	금	토

일	월	화	수	목	금	토

일	월	화	수	목	금	토