Components

DatePicker

Docs

DatePicker · DatePickerTrigger API.

API

DatePicker(루트) + DatePickerTrigger. single은 하루, duration은 start→end 기간.

import {
  DatePicker,
  DatePickerTrigger,
  DatePickerError,
  emptyDuration,
  type DatePickerDuration,
} from "@/components/datepicker";
import { Field, FieldLabel, FieldError } from "@/components/field";

const [date, setDate] = useState<Date | null>(null);
const invalid = date == null;

// 하루
<DatePicker selected={date} onChange={setDate} format="yyyy.MM.dd" />

// 필수 누락 에러 (error prop → 트리거 아래 + Context)
<DatePicker
  required
  invalid={invalid}
  error={invalid ? "필수 항목입니다." : undefined}
  selected={date}
  onChange={setDate}
/>

// DatePickerError children
<DatePicker invalid={invalid} selected={date} onChange={setDate}>
  {invalid ? <DatePickerError>필수 항목입니다.</DatePickerError> : null}
</DatePicker>

// Field · FieldLabel · FieldError 조합
<Field data-invalid={invalid || undefined}>
  <FieldLabel>예약일</FieldLabel>
  <DatePicker invalid={invalid} selected={date} onChange={setDate} />
  {invalid ? <FieldError>필수 항목입니다.</FieldError> : null}
</Field>

// 기간
<DatePicker
  mode="duration"
  duration={range}
  onDurationChange={setRange}
  format="yyyy.MM.dd"
/>

// asChild
<DatePicker selected={date} onChange={setDate}>
  <DatePickerTrigger asChild>
    <button type="button">날짜 선택</button>
  </DatePickerTrigger>
</DatePicker>

// month
<DatePicker view="month" format="yyyy.MM" selected={date} onChange={setDate} />

Props

Name	Type	Default	Description
`mode`	`"single" \| "duration"`	`"single"`	single: 하루 · duration: 한 피커에서 시작→종료.
`selected / onChange`	`Date \| null · (date) => void`	—	mode="single" 선택 날짜.
`duration / onDurationChange`	`DatePickerDuration · (d) => void`	—	mode="duration" 기간. { start, end }.
`required`	`boolean`	`false`	aria-required. 자동 검증 없음 — 앱이 invalid/error 설정.
`invalid`	`boolean`	`false`	검증 실패. 트리거 에러 보더 · aria-invalid. error 있으면 true로 취급.
`error`	`ReactNode`	—	에러 메시지. Context로 전달. DatePickerError 없으면 트리거 아래 표시.
`rangeSeparator`	`string`	`" - "`	기간 표시 구분자.
`format`	`string`	`"yyyy.MM.dd"`	date-fns 포맷. YYYY/DD 표기도 자동 변환.
`emptyLabel`	`string`	`format · format - format`	미선택 시 트리거 텍스트.
`view`	`"day" \| "month"`	`"day"`	일 달력 \| 월 달력.
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	input 기준 캘린더 열림 방향.
`popperPlacement`	`Placement`	—	floating placement 직접 지정. 있으면 side보다 우선.
`children`	`ReactNode`	—	DatePickerTrigger · DatePickerError 등. 생략 시 기본 Trigger.
`DatePickerTrigger.asChild`	`boolean`	`false`	단일 자식에 onClick/ref 병합.
`DatePickerError`	`component`	—	검증 메시지 슬롯. children 또는 Context error 표시 (FieldError와 동일 톤).

Events

Name	Signature	Description
`onChange`	`(date: Date \| null) => void`	single 날짜 선택.
`onDurationChange`	`(duration: DatePickerDuration) => void`	duration 기간 변경 (start 선택·end 선택 각각 호출).

Notes

엔진: react-datepicker (customInput = Trigger, selectsRange = duration).
필수 검증은 앱이 수행 후 invalid · error 를 넘김. required 는 aria만.
Field + FieldLabel + FieldError 조합 권장. DatePickerError 로 내장 표시도 가능.
값 지우기(X): 내장 clear 없음. Button+Icon → setDate(null) / emptyDuration().
mode="duration": 첫 클릭 start, 둘째 end. end까지 고르면 닫힘.
기간 UX 권장(강제 아님): 시작일 재설정 시 종료일을 최대 조회 기간으로 맞춤 · 종료일 선택은 시작일 이전을 minDate/disabled 로 막는 것을 우선.
side: top | bottom | left | right (기본 bottom).