DateTimePicker

날짜와 시간을 함께 선택하는 컨트롤 컴포넌트

개요

DateTimePicker는 캘린더 팝업 하단에 시간(시/분/초) 선택 영역을 함께 표시하여 날짜+시간을 동시에 선택할 수 있는 컴포넌트입니다.

주요 특징

• ✅ 날짜 + 시간 동시 선택: 캘린더 팝업 내 시간 선택 영역 포함
• ✅ 제어/비제어 패턴: value/onChange 또는 defaultValue로 값 관리
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 날짜 비활성화: inactiveMode 또는 disabledDate로 선택 제한
• ✅ 빠른 선택: shortcuts prop으로 단축 버튼 제공
• ✅ 스타일 오버라이드: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element

기본 사용

placeholder로 입력 전 안내 문구를 표시합니다.

<DateTimePicker placeholder="날짜/시간을 선택하세요" />

제어 컴포넌트

value와 onChange로 선택 값을 제어합니다.

const [value, setValue] = useState<Date | undefined>()
 
<DateTimePicker
  value={value}
  onChange={setValue}
  placeholder="날짜/시간 선택"
/>

레이블 / 필수

label prop으로 레이블을 표시하고, required로 필수 표시 기호(*)를 추가합니다.

<DateTimePicker label="예약 일시" placeholder="날짜/시간 선택" />
<DateTimePicker label="마감 일시" required placeholder="필수 입력" />

수평 레이아웃

orientation=“horizontal”이면 레이블이 왼쪽에 배치됩니다.

<DateTimePicker
  label="시작 일시"
  orientation="horizontal"
  labelWidth={80}
/>

비활성화 / 읽기 전용

disabled, readOnly 모두 비활성화 외관으로 표시되며 편집할 수 없습니다.

<DateTimePicker disabled placeholder="비활성" />
<DateTimePicker readOnly defaultValue={new Date()} />

과거 날짜 비활성화

inactiveMode로 오늘 기준 선택 가능 범위를 제한합니다.

<DateTimePicker inactiveMode="lt" placeholder="오늘 이후만 선택" />

빠른 선택

shortcuts prop으로 캘린더 위에 단축 버튼을 표시합니다.

<DateTimePicker
  shortcuts={[
    { label: "현재 시각", value: new Date() },
    { label: "내일 오전 9시", value: tomorrow },
  ]}
/>

오류 상태

error prop으로 입력란 외곽을 강조하고 오류 메시지를 표시합니다.

<DateTimePicker label="예약 일시" required error="필수 항목입니다" />

스타일 오버라이드

backgroundColor, color, borderColor 등으로 디자인 토큰을 오버라이드합니다.

<DateTimePicker
  backgroundColor="#f0fdf4"
  borderColor="#16a34a"
  color="#15803d"
/>

API Reference

Props

DateTimeInactiveMode

DateTimePickerShortcut

Ref

접근성

권장 사항

• ✅ label로 컴포넌트의 목적을 명확히 제공하세요.
• ✅ 필수 입력은 required로 설정하여 스크린 리더에 전달하세요.
• ✅ error 상태에서 aria-invalid가 자동 설정됩니다.
• ✅ disabled/readOnly 시 비활성 속성이 자동 적용됩니다.
• ✅ isSearch 모드에서 Enter 키로 검색을 트리거할 수 있습니다.

관련 컴포넌트

• DatePicker: 날짜만 선택
• TimeSelect: 시간만 선택