DatePicker
날짜를 선택할 수 있는 캘린더 기반 입력 컴포넌트
개요
DatePicker는 단일 날짜 또는 날짜 범위를 선택하는 폼 컴포넌트입니다. 캘린더 팝업과 직접 입력을 모두 지원하며, FormItem을 통합합니다.
주요 특징
- ✅ 여섯 가지 모드: 단일 날짜, 범위, 월, 연도, 월 범위, 연도 범위 선택
- ✅ 시간 선택: 날짜와 함께 시간 입력 지원
- ✅ 직접 입력: 캘린더 외 텍스트 직접 입력
- ✅ 범위 제한: minDate, maxDate 설정
- ✅ FormItem 통합: 레이블, 설명, 에러 메시지
- ✅ 접근성: 키보드 네비게이션, ARIA 속성
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Variants
단일 날짜 모드 (기본)
Preview
범위 모드
Preview
~
월 모드
Preview
연도 모드
Preview
월 범위 모드
Preview
연도 범위 모드
Preview
Variant 설명
| Variant | 설명 | 포맷 | 사용 사례 |
|---|---|---|---|
| single | 단일 날짜 선택 (기본) | YYYY.MM.DD | 특정 날짜 조회 |
| range | 시작~종료 범위 선택 | YYYY.MM.DD | 분석 기간 설정 |
| month | 월 단위 선택 | YYYY.MM | 월별 리포트 조회 |
| year | 연도 단위 선택 | YYYY | 연간 실적 조회 |
| month-range | 시작월~종료월 범위 | YYYY.MM ~ YYYY.MM | 월 범위 분석 |
| year-range | 시작년~종료년 범위 | YYYY ~ YYYY | 연도 범위 분석 |
States
Preview
날짜를 선택해주세요
분석 시작 날짜를 선택하세요
시간 선택
showTime prop을 설정하면 캘린더 하단에 시간 입력 영역이 표시됩니다. 날짜 포맷이 YYYY.MM.DD HH:mm으로 변경됩니다.
Preview
clearable 속성
clearable prop으로 선택한 날짜의 초기화 버튼 표시 여부를 제어합니다. 기본값은 true이며, false로 설정하면 초기화 버튼이 숨겨져 사용자가 한번 선택한 날짜를 지울 수 없습니다.
Preview
사용 예시
예시 1: 분석 날짜 선택
특정 날짜의 데이터를 조회합니다.
Preview
예시 2: 분석 기간 설정
시작일과 종료일을 선택합니다.
Preview
~
예시 3: 입력 포맷 고정 / 키보드 입력
각 모드별로 고정된 포맷이 적용됩니다. 키보드로 직접 입력할 수 있으며, 포맷에 맞지 않는 값 입력 시 이전 값으로 복원됩니다.
Preview
예시 4: 기간 유효성 검사
범위 모드에서 시작일이 종료일보다 이후가 되면 자동으로 유효성 검사가 동작합니다.
Preview
~
예시 5: 날짜 범위 제한
특정 범위 내에서만 날짜를 선택할 수 있습니다.
Preview
최근 90일 이내 날짜만 선택 가능
예시 6: 월별 리포트 조회
월 단위로 데이터를 조회합니다.
Preview
예시 7: 연간 실적 조회
연도 단위로 데이터를 조회합니다.
Preview
API Reference
Props (공통)
| Prop | Type | Default | Description |
|---|---|---|---|
mode | "single" | "range" | "month" | "year" | "month-range" | "year-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 | - | 종료일 플레이스홀더 |
Month Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | - | 선택된 날짜 (제어) |
defaultValue | Date | - | 기본 날짜 |
onChange | (date: Date | undefined) => void | - | 변경 핸들러 |
placeholder | string | YYYY.MM | 플레이스홀더 |
Year Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | - | 선택된 날짜 (제어) |
defaultValue | Date | - | 기본 날짜 |
onChange | (date: Date | undefined) => void | - | 변경 핸들러 |
placeholder | string | YYYY | 플레이스홀더 |
Month Range Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateRange | - | 선택된 월 범위 (제어) |
onChange | (range: DateRange | undefined) => void | - | 월 범위 변경 핸들러 |
placeholder | string | - | 플레이스홀더 |
minDate | Date | - | 선택 가능 최소 날짜 |
maxDate | Date | - | 선택 가능 최대 날짜 |
Year Range Mode Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateRange | - | 선택된 연도 범위 (제어) |
onChange | (range: DateRange | undefined) => void | - | 연도 범위 변경 핸들러 |
placeholder | string | - | 플레이스홀더 |
minDate | Date | - | 선택 가능 최소 날짜 |
maxDate | Date | - | 선택 가능 최대 날짜 |
포맷 정리
| 모드 | 포맷 | 예시 |
|---|---|---|
| single | YYYY.MM.DD | 2025.01.15 |
single + showTime | YYYY.MM.DD HH:mm | 2025.01.15 14:30 |
| range | YYYY.MM.DD | 2025.01.01 ~ 2025.01.31 |
| month | YYYY.MM | 2025.01 |
| year | YYYY | 2025 |
| month-range | YYYY.MM ~ YYYY.MM | 2025.01 ~ 2025.06 |
| year-range | YYYY ~ YYYY | 2025 ~ 2030 |
기본 사용법
import { DatePicker } from "@vortex/ui-icignal"
// 단일 날짜
<DatePicker label="날짜" />
// 범위 선택
<DatePicker mode="range" label="기간" />
// 월 선택
<DatePicker mode="month" label="월" />
// 연도 선택
<DatePicker mode="year" label="연도" />
// 월 범위 선택
<DatePicker mode="month-range" label="월 범위" />
// 연도 범위 선택
<DatePicker mode="year-range" label="연도 범위" />접근성
ARIA 속성
<DatePicker label="분석 날짜" />권장 사항
- ✅
label로 날짜 선택 목적 전달 - ✅ 키보드: Tab으로 이동, 캘린더 내 Arrow 키 네비게이션
- ✅ 날짜 형식 안내 (placeholder 활용)
- ❌ minDate/maxDate 없이 과거/미래 무제한 허용 지양
관련 컴포넌트
- DatePicker (Foundation): 기본 DatePicker
- Input: 텍스트 입력
- Select: 드롭다운 선택
- InputNumber: 숫자 입력
Last updated on