Skip to Content

DatePicker

날짜를 선택할 수 있는 캘린더 기반 입력 컴포넌트


개요

DatePicker는 단일 날짜 또는 날짜 범위를 선택하는 폼 컴포넌트입니다. 캘린더 팝업과 직접 입력을 모두 지원하며, FormItem을 통합합니다.

주요 특징

  • 여섯 가지 모드: 단일 날짜, 범위, 월, 연도, 월 범위, 연도 범위 선택
  • 시간 선택: 날짜와 함께 시간 입력 지원
  • 직접 입력: 캘린더 외 텍스트 직접 입력
  • 범위 제한: minDate, maxDate 설정
  • FormItem 통합: 레이블, 설명, 에러 메시지
  • 접근성: 키보드 네비게이션, ARIA 속성
  • 디자인 토큰: 테마 커스터마이징 지원

Variants

단일 날짜 모드 (기본)

범위 모드

~

월 모드

연도 모드

월 범위 모드

연도 범위 모드

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

분석 시작 날짜를 선택하세요

시간 선택

showTime prop을 설정하면 캘린더 하단에 시간 입력 영역이 표시됩니다. 날짜 포맷이 YYYY.MM.DD HH:mm으로 변경됩니다.

clearable 속성

clearable prop으로 선택한 날짜의 초기화 버튼 표시 여부를 제어합니다. 기본값은 true이며, false로 설정하면 초기화 버튼이 숨겨져 사용자가 한번 선택한 날짜를 지울 수 없습니다.


사용 예시

예시 1: 분석 날짜 선택

특정 날짜의 데이터를 조회합니다.

예시 2: 분석 기간 설정

시작일과 종료일을 선택합니다.

~

예시 3: 입력 포맷 고정 / 키보드 입력

각 모드별로 고정된 포맷이 적용됩니다. 키보드로 직접 입력할 수 있으며, 포맷에 맞지 않는 값 입력 시 이전 값으로 복원됩니다.

예시 4: 기간 유효성 검사

범위 모드에서 시작일이 종료일보다 이후가 되면 자동으로 유효성 검사가 동작합니다.

~

예시 5: 날짜 범위 제한

특정 범위 내에서만 날짜를 선택할 수 있습니다.

최근 90일 이내 날짜만 선택 가능

예시 6: 월별 리포트 조회

월 단위로 데이터를 조회합니다.

예시 7: 연간 실적 조회

연도 단위로 데이터를 조회합니다.


API Reference

Props (공통)

PropTypeDefaultDescription
mode"single" | "range" | "month" | "year" | "month-range" | "year-range""single"날짜 선택 모드
disabledbooleanfalse비활성화 여부
readOnlybooleanfalse읽기 전용 여부
clearablebooleantrue클리어 가능 여부
minDateDate-선택 가능 최소 날짜
maxDateDate-선택 가능 최대 날짜
widthstring | number-컴포넌트 너비
showTimebooleanfalse시간 선택 영역 표시
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
labelAlign"start" | "center" | "end"-레이블 가로 정렬
labelVerticalAlign"start" | "center" | "end"-레이블 세로 정렬
requiredbooleanfalse필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

Single Mode Props

PropTypeDefaultDescription
valueDate-선택된 날짜 (제어)
defaultValueDate-기본 날짜
onChange(date: Date | undefined) => void-날짜 변경 핸들러
placeholderstring-플레이스홀더

Range Mode Props

PropTypeDefaultDescription
value{ from: Date; to: Date }-선택된 범위 (제어)
defaultValue{ from: Date; to: Date }-기본 범위
onChange(range) => void-범위 변경 핸들러
startPlaceholderstring-시작일 플레이스홀더
endPlaceholderstring-종료일 플레이스홀더

Month Mode Props

PropTypeDefaultDescription
valueDate-선택된 날짜 (제어)
defaultValueDate-기본 날짜
onChange(date: Date | undefined) => void-변경 핸들러
placeholderstringYYYY.MM플레이스홀더

Year Mode Props

PropTypeDefaultDescription
valueDate-선택된 날짜 (제어)
defaultValueDate-기본 날짜
onChange(date: Date | undefined) => void-변경 핸들러
placeholderstringYYYY플레이스홀더

Month Range Mode Props

PropTypeDefaultDescription
valueDateRange-선택된 월 범위 (제어)
onChange(range: DateRange | undefined) => void-월 범위 변경 핸들러
placeholderstring-플레이스홀더
minDateDate-선택 가능 최소 날짜
maxDateDate-선택 가능 최대 날짜

Year Range Mode Props

PropTypeDefaultDescription
valueDateRange-선택된 연도 범위 (제어)
onChange(range: DateRange | undefined) => void-연도 범위 변경 핸들러
placeholderstring-플레이스홀더
minDateDate-선택 가능 최소 날짜
maxDateDate-선택 가능 최대 날짜

포맷 정리

모드포맷예시
singleYYYY.MM.DD2025.01.15
single + showTimeYYYY.MM.DD HH:mm2025.01.15 14:30
rangeYYYY.MM.DD2025.01.01 ~ 2025.01.31
monthYYYY.MM2025.01
yearYYYY2025
month-rangeYYYY.MM ~ YYYY.MM2025.01 ~ 2025.06
year-rangeYYYY ~ YYYY2025 ~ 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 없이 과거/미래 무제한 허용 지양

관련 컴포넌트

Last updated on