DatePicker
날짜를 선택할 수 있는 캘린더 기반 입력 컴포넌트
개요
DatePicker는 단일 날짜 또는 날짜 범위를 선택하는 폼 컴포넌트입니다. 캘린더 팝업과 직접 입력을 모두 지원하며, FormItem을 통합합니다.
주요 특징
- ✅ 두 가지 모드: 단일 날짜, 범위 선택
- ✅ 시간 선택: 날짜와 함께 시간 입력 지원
- ✅ 직접 입력: 캘린더 외 텍스트 직접 입력
- ✅ 범위 제한: minDate, maxDate 설정
- ✅ FormItem 통합: 레이블, 설명, 에러 메시지
- ✅ 접근성: 키보드 네비게이션, ARIA 속성
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Variants
단일 날짜 모드 (기본)
Preview
범위 모드
Preview
~
Variant 설명
| Variant | 설명 | 사용 사례 |
|---|---|---|
| single | 단일 날짜 선택 (기본) | 특정 날짜 조회 |
| range | 시작~종료 범위 선택 | 분석 기간 설정 |
States
Preview
날짜를 선택해주세요
분석 시작 날짜를 선택하세요
시간 선택
showTime prop을 설정하면 캘린더 하단에 시간 입력 영역이 표시됩니다. 날짜 포맷이 YYYY.MM.DD HH:mm으로 변경됩니다.
Preview
clearable 속성
clearable prop으로 선택한 날짜의 초기화 버튼 표시 여부를 제어합니다. 기본값은 true이며, false로 설정하면 초기화 버튼이 숨겨져 사용자가 한번 선택한 날짜를 지울 수 없습니다.
Preview
사용 예시
예시 1: 분석 날짜 선택
특정 날짜의 데이터를 조회합니다.
Preview
예시 2: 분석 기간 설정
시작일과 종료일을 선택합니다.
Preview
~
예시 3: 입력 포맷 고정 / 키보드 입력
날짜는 YYYY.MM.DD 포맷으로 표시되며, 입력 필드에 키보드로 직접 입력할 수 있습니다. showTime 설정 시 YYYY.MM.DD HH:mm 포맷으로 변경됩니다.
Preview
예시 4: 기간 유효성 검사
범위 모드에서 시작일이 종료일보다 이후가 되면 자동으로 유효성 검사가 동작합니다.
Preview
~
예시 5: 날짜 범위 제한
특정 범위 내에서만 날짜를 선택할 수 있습니다.
Preview
최근 90일 이내 날짜만 선택 가능
API Reference
Props (공통)
| Prop | Type | Default | Description |
|---|---|---|---|
mode | "single" | "range" | "single" | 날짜 선택 모드 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
clearable | boolean | true | 클리어 가능 여부 |
minDate | Date | - | 선택 가능 최소 날짜 |
maxDate | Date | - | 선택 가능 최대 날짜 |
width | string | number | - | 컴포넌트 너비 |
showTime | boolean | false | 시간 선택 영역 표시 |
label | string | - | 필드 레이블 |
labelWidth | string | number | - | 레이블 너비 |
labelAlign | "start" | "center" | "end" | - | 레이블 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 레이블 세로 정렬 |
required | boolean | false | 필수 여부 |
orientation | "horizontal" | "vertical" | "horizontal" | 레이블-필드 배치 방향 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | 추가 CSS 클래스 |
Single Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | - | 선택된 날짜 (제어) |
defaultValue | Date | - | 기본 날짜 |
onChange | (date: Date | undefined) => void | - | 날짜 변경 핸들러 |
placeholder | string | - | 플레이스홀더 |
Range Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | { from: Date; to: Date } | - | 선택된 범위 (제어) |
defaultValue | { from: Date; to: Date } | - | 기본 범위 |
onChange | (range) => void | - | 범위 변경 핸들러 |
startPlaceholder | string | - | 시작일 플레이스홀더 |
endPlaceholder | string | - | 종료일 플레이스홀더 |
기본 사용법
import { DatePicker } from "@vortex/ui-icignal"
// 단일 날짜
<DatePicker label="날짜" />
// 범위 선택
<DatePicker mode="range" label="기간" />접근성
ARIA 속성
<DatePicker label="분석 날짜" />권장 사항
- ✅
label로 날짜 선택 목적 전달 - ✅ 키보드: Tab으로 이동, 캘린더 내 Arrow 키 네비게이션
- ✅ 날짜 형식 안내 (placeholder 활용)
- ❌ minDate/maxDate 없이 과거/미래 무제한 허용 지양
관련 컴포넌트
- DatePicker (Foundation): 기본 DatePicker
- Input: 텍스트 입력
- Select: 드롭다운 선택
- InputNumber: 숫자 입력
Last updated on